On Tue, 16 Feb 2021 at 16:06, Daniel Ebdrup Jensen <[email protected]> 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 <[email protected]> > 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 < > [email protected]> > >> >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! _______________________________________________ [email protected] mailing list https://lists.freebsd.org/mailman/listinfo/freebsd-doc To unsubscribe, send any mail to "[email protected]"
