From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from cn.fujitsu.com ([59.151.112.132]:51545 "EHLO heian.cn.fujitsu.com" rhost-flags-OK-FAIL-OK-FAIL) by vger.kernel.org with ESMTP id S1750789AbaETAdX convert rfc822-to-8bit (ORCPT ); Mon, 19 May 2014 20:33:23 -0400 Message-ID: <537AA30B.1050909@cn.fujitsu.com> Date: Tue, 20 May 2014 08:34:19 +0800 From: Qu Wenruo MIME-Version: 1.0 To: , Hugo Mills , , Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand. References: <1396427378-10487-1-git-send-email-quwenruo@cn.fujitsu.com> <20140416171219.GC29256@twin.jikos.cz> <20140517174315.GC2537@carfax.org.uk> <20140519140123.GG31608@suse.cz> <20140519143342.GH31608@suse.cz> In-Reply-To: <20140519143342.GH31608@suse.cz> Content-Type: text/plain; charset="UTF-8"; format=flowed Sender: linux-btrfs-owner@vger.kernel.org List-ID: -------- Original Message -------- Subject: Re: [PATCH 00/27] Replace the old man page with asciidoc and man page for each btrfs subcommand. From: David Sterba To: Hugo Mills , Qu Wenruo , linux-btrfs@vger.kernel.org, clm@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:][+/-][gkm]|[devid:]max :: >>> >>> 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\fP[gkm]|[\fIdevid\fP:]\fImax \fP >> I think we can restore the formatting with asciidoc. >> >> The line above would become: >> >> *btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]'max ' >> >> or with bold max >> >> *btrfs* *filesystem resize* ['devid':][+/-]'size'[kgm]|[devid':]*max* '' > The correct base string should read > > btrfs filesystem resize [:][+/-][kgm]|[:]max > > 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