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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html