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.
> 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?
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
