From owner-freebsd-doc@freebsd.org Wed Mar 3 23:36:41 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 D2457554DFC for ; Wed, 3 Mar 2021 23:36:41 +0000 (UTC) (envelope-from crees@freebsd.org) Received: from mail267c50.megamailservers.eu (mail1425c50.megamailservers.eu [91.136.14.25]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4DrVkx1HtDz3mnR; Wed, 3 Mar 2021 23:36:40 +0000 (UTC) (envelope-from crees@freebsd.org) X-Authenticated-User: crees@uwclub.net DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=megamailservers.eu; s=maildub; t=1614814599; bh=hhCobZkUdcdfG9UEmzfEEwZm4OEponoECZbW4g0qovA=; h=Subject:To:References:From:Date:In-Reply-To:From; b=qsJCh+Oj3RBR9hjrWFPn61KzIweJwyhhquZW5YWpi9KXlHez6xhHxEKeRCOwSM8pj raEkWmA1Zre94x91DQjtki86T/9xlBZb//Y505QSx/SnJU5XjXp+0SQTPUZenZOvZU vUP1TpiYdM7TYbSLAxnkhTDXta7m1xBA3oNjJepI= Feedback-ID: crees@freebsd.o Received: from pegasus.bayofrum.net (81-178-238-223.dsl.pipex.com [81.178.238.223]) (authenticated bits=0) by mail267c50.megamailservers.eu (8.14.9/8.13.1) with ESMTP id 123Nabiw016409; Wed, 3 Mar 2021 23:36:38 +0000 X-Spam-Status: No X-bayofrum-MailScanner-From: crees@freebsd.org X-bayofrum-MailScanner: Found to be clean X-bayofrum-MailScanner-ID: 89B73E601.A871E X-bayofrum-MailScanner-Information: Please contact the ISP for more information Received: from [192.168.1.127] (POSEIDON.bayofrum.net [192.168.1.127]) by pegasus.bayofrum.net (Postfix) with ESMTPSA id 89B73E601; Wed, 3 Mar 2021 23:36:30 +0000 (GMT) Subject: Re: Regarding AsciiDoctor and long lines To: freebsd-doc@freebsd.org, blackend@FreeBSD.org, carlavilla@FreeBSD.org, Daniel Ebdrup Jensen References: <20210212170859.lzzj5qrriovjd2ux@nerd-thinkpad.local> <20210216074810.qwaotlonqdaulvk2@nerd-thinkpad.local> <20210216141620.k4rwqtvwfnhk7xty@nerd-thinkpad.local> <20210216150558.psilddo4pglnpoff@nerd-thinkpad.local> From: Chris Rees Message-ID: Date: Wed, 3 Mar 2021 23:36:28 +0000 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.7.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-GB Content-Transfer-Encoding: 8bit X-CTCH-RefID: str=0001.0A742F1E.60401D86.0061, ss=1, re=0.000, recu=0.000, reip=0.000, cl=1, cld=1, fgs=0 X-CTCH-VOD: Unknown X-CTCH-Spam: Unknown X-CTCH-Score: 0.000 X-CTCH-Rules: X-CTCH-Flags: 0 X-CTCH-ScoreCust: 0.000 X-CSC: 0 X-CHA: v=2.3 cv=IrRgj43g c=1 sm=1 tr=0 a=VPjlEbx5XC2baNimRf67MQ==:117 a=VPjlEbx5XC2baNimRf67MQ==:17 a=IkcTkHD0fZMA:10 a=dESyimp9J3IA:10 a=6I5d2MoRAAAA:8 a=UxTq5REuAAAA:20 a=ZB5LerlCAAAA:8 a=ubIRpzF0TJmajQZTPO8A:9 a=QEXdDO2ut3YA:10 a=IjZwj45LgO3ly-622nXo:22 a=YKPTzOroS2oaEK2QgPcx:22 a=BPzZvq435JnGatEyYwdK:22 X-Origin-Country: GB X-Rspamd-Queue-Id: 4DrVkx1HtDz3mnR X-Spamd-Bar: / Authentication-Results: mx1.freebsd.org; none X-Spamd-Result: default: False [0.00 / 15.00]; local_wl_from(0.00)[freebsd.org]; ASN(0.00)[asn:9115, ipnet:91.136.0.0/17, country:CA] 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: Wed, 03 Mar 2021 23:36:41 -0000 Hi all (please forgive any duplicates, I posted with the wrong email and got bounced from the list :() On 16/02/2021 15:36, Sergio Carlavilla wrote: > 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 é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 <>> 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 <> 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! 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