On Sat, May 17, 2014 at 06:43:15PM +0100, Hugo Mills wrote: > On Wed, Apr 16, 2014 at 07:12:19PM +0200, David Sterba wrote: > > On Wed, Apr 02, 2014 at 04:29:11PM +0800, Qu Wenruo wrote: > > > Convert the old btrfs man pages to new asciidoc and split the huge > > > btrfs man page into subcommand man page. > > > > I'm merging this patchset into the base series of integration because > > several patches need to update the docs and it's no longer feasible to > > keep it in a separate branch from the patches. > > I've just been poking around in the docs for a completely different > reason, and I think there's a fairly serious problem (well, as serious > as problems get with documentation). > > Take, for example, the format for btrfs fi resize: > > 'resize' [devid:][+/-]<size>[gkm]|[devid:]max <path>:: > > Now, this has just thrown away all of the useful markup which > indicates the semantics of the command. The asciidoc renders all of > that text literally and unformatted, making alphasymbolic(*) soup of > the docs. Compare this to the old roff man page: > > \fBbtrfs\fP \fBfilesystem resize\fP > [\fIdevid\fP:][+/\-]\fI<size>\fP[gkm]|[\fIdevid\fP:]\fImax <path>\fP > > This isn't perfect -- we're missing a \fB around the "max" -- but > it has text in bold(⁑) and italics(⁂) and neither(☃). I've just looked > at some of the other pages, and they've also got similar typographical > problems. This is a lot of fiddly tedious work to get it right, and if > it doesn't get done now in the initial commit, then we're going to end > up with poor examples copied for every new feature or docs update, > making the problem worse before anyone does the work to make it > better.
Oh, and asciidoc appears to be the most horrible capricious inconsistent parser in existence. I've just spent 5 minutes getting this one line of text to do what I want it to: ===== __N__**c**[\[_Mmin_**-**]__Mmax__**s**[_P_**p**]] ===== I had to run through the list of block quote operators one at a time in order to find the one I needed for this (the =====); it's still not indenting it correctly on the resulting man page. Note also the fun things like the fact that [[]] is special, so you have to quote the opening part of it -- but if you try quoting the first [ with a \ you get a literal \[ in the output. You get the right output from quoting the *second* [ only. The Nc can only be italicised and emboldened properly with __ and ** because _ and * require whitespace around them in order to work (seriously, WTF?). However, we can't be consistent with that in the _Mmin_**-** because the quoted \[ appears to count as whitespace, so using __Mmin__ gives us a leading literal _. The closing __ appears to close the single opening _ correctly in that case, though. Seriously, this is meant to be _easy_ to use? I think I'd rather type docbook by hand that have to struggle with this. Even the troff macros for man pages are simpler to get right. Hugo. > Hugo. > > (*) Or possibly alphashambolic. :) > (⁑) For literal text > (⁂) For variables that require substitution by the user > (☃) For structural syntax indicators such as [] for optional parts, | > for alternation and ... to indicate optional continuation of a list > -- === Hugo Mills: hugo@... carfax.org.uk | darksatanic.net | lug.org.uk === PGP key: 65E74AC0 from wwwkeys.eu.pgp.net or http://www.carfax.org.uk --- Great oxymorons of the world, no. 1: Family Holiday ---
signature.asc
Description: Digital signature
