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.
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
--- There isn't a noun that can't be verbed. ---
signature.asc
Description: Digital signature
