Date: Tue, 16 Feb 2021 16:36:01 +0100 From: Sergio Carlavilla <carlavilla@freebsd.org> To: Daniel Ebdrup Jensen <debdrup@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: Regarding AsciiDoctor and long lines Message-ID: <CAFwocyPR7ReP19xx0U=t56oXP5g0X85iPv7LiAz=1AOhU-onbA@mail.gmail.com> In-Reply-To: <20210216150558.psilddo4pglnpoff@nerd-thinkpad.local> References: <YCZ4TedB5G1sI8L1@emphyrio.blackend.org> <CAFwocyOYepw%2BntThzGp8ZNKQrPHm9bzgK60_fpfu1BZ5v39y9Q@mail.gmail.com> <20210212170859.lzzj5qrriovjd2ux@nerd-thinkpad.local> <CAFwocyOdSqnVUcRgUhiecXvG2qGasnL2VU0JugwEVc-WuvJxOg@mail.gmail.com> <CAFwocyOBLW0Siwtk0A%2BQox_MQt4KqCnMvHa_1s23RmjqqmLUkw@mail.gmail.com> <YCq31UMUj8DH2En3@emphyrio.blackend.org> <20210216074810.qwaotlonqdaulvk2@nerd-thinkpad.local> <CAOa83AcBASoD=tOxx6xtAwtf5Wz7XeTm3qacBpM9dxYvX7C0LQ@mail.gmail.com> <20210216141620.k4rwqtvwfnhk7xty@nerd-thinkpad.local> <CAFwocyP5gWMpxEqOK1ktujX-h6Re9=y3orx5zm=anYRVgwYoWg@mail.gmail.com> <20210216150558.psilddo4pglnpoff@nerd-thinkpad.local>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, 16 Feb 2021 at 16:06, Daniel Ebdrup Jensen <debdrup@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@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@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 =C3=A9crit : > >> >> >> > >> >> >> 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, variabl= es > >> >> 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 obtus= e > - > >> >> 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 i= s > >> >problematic to hard wrap text but that suggests that there's a toolin= g > >> >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 handboo= k > >> 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.ado= c > - > >> and it produced [1]. > >> > >> Aside from things which I think can be addressed separately, the chang= e > >> 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]] > >=3D=3D 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]] > >=3D=3D 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=E2=80=99m gonna talk about the diffs with the AsciiDoctor team, maybe the= y can help as with this bikeshed. As I said before, I don=E2=80=99t like the diffs behavior right now too. It= =E2=80=99s a problem. Bye!
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAFwocyPR7ReP19xx0U=t56oXP5g0X85iPv7LiAz=1AOhU-onbA>