Regarding AsciiDoctor and long lines

[Allan Jude]

On 2021-02-10 09:31, Sergio Carlavilla wrote:
> On Wed, 10 Feb 2021 at 15:07, Daniel Ebdrup Jensen <debdrup at freebsd.org> wrote:
>>
>> On Wed, Feb 10, 2021 at 02:57:34PM +0100, Andreas B wrote:
>>> Have you considered one sentence per line?
>>>
>>> Ref. https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line.
>>>
>>> Andreas
>>>
>>> On Wed, Feb 10, 2021 at 2:50 PM Daniel Ebdrup Jensen
>>> <debdrup at freebsd.org> wrote:
>>>>
>>>> Hi folks,
>>>>
>>>> Pursuant to a conversation that was had on #bsddocs on EFnet, this is
>>>> mostly me wondering if we can adopt a new standard practice.
>>>>
>>>> Since the AsciiDoctor conversion, it's become evident that reading diffs
>>>> which exceed the usual 72 columns that FreeBSD has standardized on for
>>>> style(9) is less than great, especially as some of the sentences in the
>>>> documentation can be rather long.
>>>>
>>>> So I would love if it we can agree to wrap/justify lines to 72 columns,
>>>> going forward whenever we touch files.
>>>>
>>>> I've already started doing this on the handbook/x11 chapter update that
>>>> I'm working on, and it's in line with what we're used to from DocBook,
>>>> so I don't think it's too much of a big ask? :)
>>>>
>>>> We also need to decide about it relatively soon, since the Weblate
>>>> project needs to know about about it, as it involves their use of .so
>>>> files (although the details somewhat escaped me when I read it after
>>>> staying up all night, so perhaps a domain expert can fill in the blanks
>>>> here?).
>>>>
>>>> For reference, my testing had led me to believe that AsciiDoctor doesn't
>>>> care one bit how it's styled, as long as the actual markup is kept the
>>>> same.
>>>>
>>>> I'm open to feedback about it, of course, but it seems like a very
>>>> sensible change to me.
>>>>
>>>> Yours hopefully,
>>>> Daniel Ebdrup Jensen
>>> _______________________________________________
>>> freebsd-doc at freebsd.org mailing list
>>> https://lists.freebsd.org/mailman/listinfo/freebsd-doc
>>> To unsubscribe, send any mail to "freebsd-doc-unsubscribe at freebsd.org"
>>
>> Sure, that seems like a nice compromise.
>>
>> I mostly want some kind of consensus so we can move forward without
>> having to deal with these extremely long lines. ;)
>>
>> Yours,
>> Daniel Ebdrup Jensen
> 
> Hi,
> 
> Personally I prefer to continue with the "one sentence per line".
> IMHO this allows people to get focused in writing text.
> 
> But apart from what the AsciiDoctor recommends about using the "one
> sentece per line".
> There would be some problems with this approach.
> 
> In the paragraph there's no problems because you can split a paragraph
> into multiple
> lines and it works well.
> 
> For example, in AsciiDoctor this is the same:
> 
> - Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
> eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
> minim veniam, quis nostrud exercitation ullamco laboris nisi ut
> aliquip ex ea commodo consequat. D
> 
> - Lorem ipsum dolor sit amet,
> consectetur adipiscing elit,
> sed do eiusmod tempor
> 
> In AsciiDoctor to create a new paragraph you have two options, keep a empty
> line between two lines or use the "plus" character. For example:
> 
> This is a +
> line break.
> 
> But you should use the "one sentence per line" in: headings, unordered list,
> ordered list, images, included files, and maybe with some custom extensions.
> 
> For example, try to make this:
> 
> * this is a very very very very (image reached the 72 characters)
> list
> * and this is the second item in the list
> 
> Or for example:
> 
> == This is a looooooooong (the same, we reached the 72 characters)
> heading
> 
> I think you got the point.
> 
> Maybe we can find a solution with the diff tool.
> 
> Bye!
> _______________________________________________
> freebsd-doc at freebsd.org mailing list
> https://lists.freebsd.org/mailman/listinfo/freebsd-doc
> To unsubscribe, send any mail to "freebsd-doc-unsubscribe at freebsd.org"
> 

There was also some mention that one sentence per line is helpful to the
translators.

The translation system will mark a re-wrapped line as 'fuzzy', and
needing someone to re-confirm the translation. It isn't like they need
to retranslate it, but, still.

I imagine something like what we do for man pages, new sentence should
always start on a new line.

-- 
Allan Jude