Re: [PATCH] Documentation: fix broken conversion

[Qu Wenruo]

-------- Original Message --------
Subject: [PATCH] Documentation: fix broken conversion
From: Peter Wu <pe...@lekensteyn.nl>
To: <linux-btrfs@vger.kernel.org>
Date: 2015年01月05日 22:10
Fixes various formatting issues:
Fixes quoting issues in various manpages. Before/After excerpts for
mkfs.btrfs(8), btrfs-qgroup(8):

     mkfs.btrfs [-A|--alloc-start '<alloc-start>']
     mkfs.btrfs [-A|--alloc-start <alloc-start>]
     id 0/<subvolume id>''
     id 0/<subvolume id>
     If multiple '<attr>'s is given, use comma to separate.
     If multiple <attr>s is given, use comma to separate.

The one that is most apparent is the removal of text in
btrfs-subvolume(8) and others. Before/After:

     list [options] [-G <value>] [-C <value>] [--sort=rootid,gen,ogen,path] 
<path>
     list [options] [-G [+|-]<value>] [-C [+|-]<value>] [--sort=rootid,gen,ogen,path] 
<path>
     create [-i <qgroupid>] <name>
     create [-i <qgroupid>] [<dest>]<name>
Nice catch!

This happens because `<foo>` was replaced by `'<foo>'` in the sed
expression, which is then treated as a constrained quote. As a result,
the `[...]` before the string gets interpreted as "quoted text
attributes".

In this patch, the sed expression is dropped and asciidoc is configured
to recognize `<...>` as a unconstrained quoted string (such that
`<attr>s` is correctly emphasized) and to avoid adding quotes in
contexts where it is not needed.

A remaining problem is that some texts (the one between brackets) do not
add the emphasis for `<...>`.
IMHO, current implement in this patch is already good enough, although 
it is still not perfect,
but much much better than previous one and such missing of emphasize is 
acceptable.
While this could be solved by replacing
`[` and `]` with `&#91;` and `&#93;` using sed, it introduces formatting
problems in btrfs-zero-log(8) because the context is ignored.

Signed-off-by: Peter Wu <pe...@lekensteyn.nl>
---
  Documentation/Makefile      | 8 +++-----
  Documentation/asciidoc.conf | 6 ++++++
  2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index ef4f1bd..72ab77b 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -113,10 +113,8 @@ clean:
        $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
  
  %.xml : %.txt asciidoc.conf
-       $(QUIET_ASCIIDOC)$(RM) $@.tmp[12] $@ && \
-       sed -e "s/\(<[^>]\+>\)/'\1'/g" < $< > $@.tmp1 && \
+       $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
        $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
                $(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \
-               -o $@.tmp2 $@.tmp1 && \
-       mv $@.tmp2 $@ && \
-       rm -f -- $@.tmp1
+               -o $@+ $< && \
+       mv $@+ $@
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 313f185..1ea7459 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -10,6 +10,12 @@
  [macros]
  (?su)[\\]?(?P<name>linkbtrfs):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
  
+[tags]
+bracket-emphasis={1?[{1}]}<emphasis>&lt;|&gt;</emphasis>
+
+[quotes]
+&lt;|&gt;=#bracket-emphasis
+
This method is more elegant than the original sed method.

Thanks a lot.
Qu
  [attributes]
  asterisk=&#42;
  plus=&#43;

--
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