Regarding AsciiDoctor and long lines

[Sergio Carlavilla]

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.

Bye!