Regarding AsciiDoctor and long lines

Wed Feb 10 16:03:50 UTC 2021

On Wed, Feb 10, 2021 at 09:52:26AM -0500, Allan Jude wrote:
>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
>_______________________________________________
>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"

Yeah, I'm perfectly fine with doing it like how manual pages work, ie.
the one-sentence-per-line workflow, if I understand it.

I'll be re-working the handbook/x11 chapter to that at some point. :)

Yours,
Daniel Ebdrup Jensen
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 618 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20210210/f323ed22/attachment.sig>