Regarding AsciiDoctor and long lines

[Sergio Carlavilla]

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!