-------- Original Message --------
Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and
man page for each btrfs subcommand.
From: David Sterba <dste...@suse.cz>
To: Hugo Mills <h...@carfax.org.uk>, Qu Wenruo
<quwen...@cn.fujitsu.com>, linux-btrfs@vger.kernel.org, c...@fb.com
Date: 2014年05月19日 22:33
On Mon, May 19, 2014 at 04:01:23PM +0200, David Sterba wrote:
On Sat, May 17, 2014 at 06:43:15PM +0100, Hugo Mills wrote:
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
I think we can restore the formatting with asciidoc.
The line above would become:
*btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]'max <path>'
or with bold max
*btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]*max* '<path>'
The correct base string should read
btrfs filesystem resize [<devid>:][+/-]<size>[kgm]|[<devid>:]max <path>
ie. add <..> around devid and size. That way it's copy-paste-ready.
In this case the italic/underlined text does not IMO add much value.
It is completely OK for me.
Since the base string is copy-paste-ready, it would add any extra effort
to add other markup.
My personal feeling about the enriched formatting is that the commands
stand out of the text and are easier to catch (as you've mentioned
somewhere in the thread).
The bolded subcommand name seems to be sufficent.
The files are processed by XSL, I think it should be possible to apply
some transformation that would add '...' around <...> automatically
instead of making everybody write that.
Proposed changes:
- format all subcommands as bold instead of italic ('' -> **)
- add all missing <...>
- find a way how to add '...' around <...> (xsl or sed or whatever)
Does that work for you?
That is OK for me, I'll investigate it.
Should I send a new patchset or just delta patches upon the current base?
Thanks,
Qu
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
