Date: Tue, 16 Feb 2021 16:05:58 +0100 From: Daniel Ebdrup Jensen <debdrup@FreeBSD.org> To: freebsd-doc@freebsd.org Subject: Re: Regarding AsciiDoctor and long lines Message-ID: <20210216150558.psilddo4pglnpoff@nerd-thinkpad.local> In-Reply-To: <CAFwocyP5gWMpxEqOK1ktujX-h6Re9=y3orx5zm=anYRVgwYoWg@mail.gmail.com> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
--4n2xtkifyxiljw3f Content-Type: text/plain; charset=iso-8859-1; format=flowed Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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> w= rote: >> >> 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 =E9crit : >> >> >> >> >> >> I think the doceng team should pronounce about this. >> >> >> >> >> >> IMHO, use the 72 characters per line would be a problem in the fut= ure. >> >> >> >> >> > >> >> >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 k= ept >> >> 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 whitespa= ce >> >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]] >=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 responsibili= ty > 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" approac= h. > >IMHO, the other approach returns to the "Docbook approach". > >Bye. > >[1] https://raw.githubusercontent.com/freebsd/freebsd-doc/main/documentati= on/content/en/books/handbook/desktop/_index.adoc >[2] https://raw.githubusercontent.com/freebsd/freebsd-quarterly/master/rep= ort-sample.adoc Hi folks, So, at least for simple paragraphs, one sentence per line is largely=20 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=20 make it easy to review, while also keeping it easy to write. Yours, Daniel Ebdrup Jensen --4n2xtkifyxiljw3f Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQGTBAABCgB9FiEEDonNJPbg/JLIMoS6Ps5hSHzN87oFAmAr31ZfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDBF ODlDRDI0RjZFMEZDOTJDODMyODRCQTNFQ0U2MTQ4N0NDREYzQkEACgkQPs5hSHzN 87r5rQf9E4pW03QjHULD+tdIKFgF4MtSJFiPPbhbUHhCIeXLL44TWZLcea5guUoW 1YlaC5VsM9uYlHs8TdoefQc/vwPNbpJOfT/1/QoQQnlNOrA/Cap7SvyckT79at4J uvqMI6rJaLONKlkh1lZpuRrUzZe8z7u34MeWas6fsjIRFvmTW8MHcQtnacRZpRM3 Wg39yQ8JmffS9QKawgi/rBRWD+ThDLOcpgjIxEoxxRHlFpvYBk4GzDgWPdcc25Qh dvG9+++5KvbPyzFe1G9+Qo9DFVK/O4AjcLcnfC0OHn0dpaJhIuMSQk9dpR24Qp62 YGkEz79T+r5Z0G3gvwn8lso9Z/eXQA== =5lcR -----END PGP SIGNATURE----- --4n2xtkifyxiljw3f--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20210216150558.psilddo4pglnpoff>