From owner-freebsd-doc@freebsd.org Tue Feb 16 15:36:14 2021 Return-Path: Delivered-To: freebsd-doc@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 2D9D453C6EC for ; Tue, 16 Feb 2021 15:36:14 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [96.47.72.83]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Dg4nV0d07z4bWb; Tue, 16 Feb 2021 15:36:14 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: from mail-lf1-f47.google.com (mail-lf1-f47.google.com [209.85.167.47]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) (Authenticated sender: carlavilla) by smtp.freebsd.org (Postfix) with ESMTPSA id EEADE20C3D; Tue, 16 Feb 2021 15:36:13 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: by mail-lf1-f47.google.com with SMTP id p21so16399525lfu.11; Tue, 16 Feb 2021 07:36:13 -0800 (PST) X-Gm-Message-State: AOAM533/ymAubPJfIvR1wHYrIK05q9f8SwEE28H1GiILiZwzj7mxcEwA 0vhX+y2eWG8+VuxO9ZAXFWKw/ZZadbDjn2obUPM= X-Google-Smtp-Source: ABdhPJwV9MU7bQnb8M4qaG+AU31Q2PD2vVNwgJ5/DkbyF8VRVeQq16MczF4W6dWVu08llZCBwtzCKFXkxExEVGfLnAY= X-Received: by 2002:a05:6512:1108:: with SMTP id l8mr11749356lfg.255.1613489772304; Tue, 16 Feb 2021 07:36:12 -0800 (PST) MIME-Version: 1.0 References: <20210212170859.lzzj5qrriovjd2ux@nerd-thinkpad.local> <20210216074810.qwaotlonqdaulvk2@nerd-thinkpad.local> <20210216141620.k4rwqtvwfnhk7xty@nerd-thinkpad.local> <20210216150558.psilddo4pglnpoff@nerd-thinkpad.local> In-Reply-To: <20210216150558.psilddo4pglnpoff@nerd-thinkpad.local> From: Sergio Carlavilla Date: Tue, 16 Feb 2021 16:36:01 +0100 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: Regarding AsciiDoctor and long lines To: Daniel Ebdrup Jensen , freebsd-doc@freebsd.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Content-Filtered-By: Mailman/MimeDel 2.1.34 X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 16 Feb 2021 15:36:14 -0000 On Tue, 16 Feb 2021 at 16:06, Daniel Ebdrup Jensen 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 > 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 < >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 <> 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!