Regarding AsciiDoctor and long lines

Thu Mar 4 16:28:46 UTC 2021

On Thu, 4 Mar 2021 at 00:14, Chris Rees <crees at bayofrum.net> wrote:
>
> 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

Hi,

Thanks for that :)

Sorry for don't publishing the latest news here.
I talked about this problem with Dan Allen, the creator of AsciiDoctor in
the AsciiDoctor's Gitter channel.
In Dan Allen's opinion the best approach it's to use the "one sentence per
line".

He shared with me this link [1] to clarify the approach.
And as I said a couple of times before.
*What we have right now it's ***not*** the "one sentence per line
approach", it's the result of a mechanical conversion*

Bye and thanks for this!

[1] https://sembr.org/