Regarding AsciiDoctor and long lines

[Chris Rees]

Hi all,

On 16/02/2021 15:36, Sergio Carlavilla wrote:
> On Tue, 16 Feb 2021 at 16:06, Daniel Ebdrup Jensen <debdrup at freebsd.org>
> wrote:
> 
>> On Tue, Feb 16, 2021 at 03:39:55PM +0100, Sergio Carlavilla wrote:
>>> On Tue, 16 Feb 2021 at 15:16, Daniel Ebdrup Jensen <debdrup at freebsd.org>
>> wrote:
>>>>
>>>> On Tue, Feb 16, 2021 at 01:01:45PM +0000, Ceri Davies wrote:
>>>>> On Tue, 16 Feb 2021 at 07:48, Daniel Ebdrup Jensen <
>> debdrup at freebsd.org>
>>>>> wrote:
>>>>>
>>>>>> On Mon, Feb 15, 2021 at 07:05:09PM +0100, Marc Fonvieille wrote:
>>>>>>> Le 12.02.2021 18:24, Sergio Carlavilla a écrit :
>>>>>>>>
>>>>>>>> I think the doceng team should pronounce about this.
>>>>>>>>
>>>>>>>> IMHO, use the 72 characters per line would be a problem in the
>> future.
>>>>>>>>
>>>>>>>
>>>>>>> Why it would be a problem?
>>>>>>>
>>>>>>> --
>>>>>>> Marc
>>>>>>
>>>>>> Hi folks,
>>>>>>
>>>>>> Can we make a compromise where real paragraphs, ie. the only things
>>>>>> which don't seem to need much in the way of AsciiDoctor markup, are
>> kept
>>>>>> at 72 columns, and headings, lists, images, include macros, variables
>>>>>> and custom macros are allowed to go beyond the 72 columns?
>>>>>> If they have to, there's always word-smithing options for trying to
>> be
>>>>>> as concise as possible (without, of course, making things too obtuse
>> -
>>>>>> it's a tough balance, admittedly?
>>>>>>
>>>>>> That seemed to work for DocBook, so is there a reason it won't work
>>>>>> here?
>>>>>>
>>>>>
>>>>>   For HTML output it doesn't look like it's an issue; although
>> whitespace
>>>>> is preserved in the output, it's luckily irrelevant to HTML output.
>>>>>
>>>>> For other output formats such as PDF or mdoc then I can see that it is
>>>>> problematic to hard wrap text but that suggests that there's a tooling
>>>>> issue; Marc's need to be able to actually see what has changed is
>> really
>>>>> important.
>>>>>
>>>>> Butting out for another 9 years now :D
>>>>>
>>>>> Ceri
>>>>
>>>> I don't see how mdoc would be impacted, since that lives in the src
>>>> repo.
>>>>
>>>> As for pdf files, I couldn't tell you the last time I used the handbook
>>>> in a pdf format, so I had to generate it by grabbing asciidoctor-pdf
>>>> and running it on doc/documentation/content/en/books/handbook/book.adoc
>> -
>>>> and it produced [1].
>>>>
>>>> Aside from things which I think can be addressed separately, the change
>>>> I made in order to test the theories that pdf should work with extra
>>>> linebreaks inserted at 72 columns, is on page 21, on the paragraph
>>>> "The hardware requirements to install FreeBSD vary by.."
>>>>
>>>> To me, this looks exactly like how I would expect it to look.
>>>> So I think we'll be fine with this change, at least for newlines as it
>>>> relates to paragraphs.
>>>>
>>>> Yours,
>>>> Daniel Ebdrup Jensen
>>>>
>>>> [1]: https://people.freebsd.org/~debdrup/book.pdf
>>>
>>> Hi,
>>>
>>> I think that I did not explain my position correctly hehehe.
>>>
>>> What we have *right now* it's the result of a mechanical conversion.
>>> What we have right now *it's not* the "one sentence per line" that the
>>> AsciiDoctor team recommends. What we have right now it's the result
>>> of converting Docbook to AsciiDoc automatically.
>>>
>>> So for example, is we took for example this paragraph from[1]:
>>>
>>> [[desktop-productivity]]
>>> == Productivity
>>>
>>> When it comes to productivity, users often look for an office suite or
>>> an easy-to-use word processor. While some <<x11-wm,desktop
>>> environments>> like KDE provide an office suite, there is no default
>>> productivity package. Several office suites and graphical word
>>> processors are available for FreeBSD, regardless of the installed
>>> window manager.
>>>
>>> Using the one sentence per line would be:
>>>
>>> [[desktop-productivity]]
>>> == Productivity
>>>
>>> When it comes to productivity, users often look for an office suite or
>>> an easy-to-use word processor. (new line)
>>> While some <<x11-wm,desktop environments>> like KDE provide an office
>>> suite, there is no default productivity package. (new line)
>>> Several office suites and graphical word processors are available for
>>> FreeBSD, regardless of the installed window manager. (new line)
>>>
>>> I don't see the problem of using this approach.
>>>
>>> But I see a lot of problems using the 72 line approach.
>>>
>>> What problems?
>>> - Headings, unordered list, ordered list, qandas, tables and a long etc...
>>> - Another problem? Right now the paragraphs work as you expected
>>>   with the 72 characters per line, but what gonna happen if the
>> AsciiDoctor
>>>   team changes this in the future? How is going to assume the
>> responsibility
>>>   of changing everything to fit the new requirements?
>>>   The good point of this is that AsciiDoctor is under heavy development.
>>>
>>> And of course, I'm not saying that the current behaviour with the
>>> diff's are correct.
>>> I know that right now it's *****very***** difficult to read the diffs.
>>>
>>> For example, you can read an example of the "one sentence per line"
>> here[2].
>>> I think here[2] you can see very clear the "one sentence per line"
>> approach.
>>>
>>> IMHO, the other approach returns to the "Docbook approach".
>>>
>>> Bye.
>>>
>>> [1]
>> https://raw.githubusercontent.com/freebsd/freebsd-doc/main/documentation/content/en/books/handbook/desktop/_index.adoc
>>> [2]
>> https://raw.githubusercontent.com/freebsd/freebsd-quarterly/master/report-sample.adoc
>>
>> Hi folks,
>>
>> So, at least for simple paragraphs, one sentence per line is largely
>> orthogonal to whether we try to wrap paragraphs at 72 columns?
>>
>> I'm not sure what the solution is here, unfortunately. I'd just like to
>> make it easy to review, while also keeping it easy to write.
>>
>> Yours,
>> Daniel Ebdrup Jensen
>>
> Hi,
> 
> I’m gonna talk about the diffs with the AsciiDoctor team, maybe they can
> help as with this bikeshed.
> 
> As I said before, I don’t like the diffs behavior right now too. It’s a
> problem.
> 

As I see it, reading the diffs is the biggest issue.

I've made a little utility that I've called difffold (like fold, but for 
patches).

https://www.bayofrum.net/~crees/scratch/difffold.py

It obviously breaks the diff, so I guess I could make it also comment 
out the @@ lines or something just in case anyone were insane enough to 
try to run patch on it, but I think it does exactly what Marc wants?

https://www.bayofrum.net/~crees/scratch/difffold_example

I reckon it'd be pretty easy to put into a Sieve filter or something.

It passes through the rest of any file completely untouched.

Chris