Introduce an asciidoc.conf file with the purpose of adding a gitlink: macro
which will improve the manpage output. Most notably this changes the following
in cogito.7

       cg-add: cg-add.html [-N] FILE...
              Add files to the GIT repository.

       cg-branch-add: cg-branch-add.html BRANCH_NAME LOCATION
              Add new branch to the GIT repository.


       cg-add [-N] FILE...
              Add files to the GIT repository.

       cg-branch-add BRANCH_NAME LOCATION
              Add new branch to the GIT repository.

Signed-off-by: Jonas Fonseca <[EMAIL PROTECTED]>

I only did the Cogito part, since it was a lot easier. If this is
desirable for the GIT core manpages I'd be happy to provide a similar
patch to remove the confusing .html links from GIT manpages.

 Documentation/Makefile             |    4 ++--
 Documentation/asciidoc.conf        |   18 ++++++++++++++++++
 Documentation/make-cg-asciidoc     |    6 +++---
 Documentation/make-cogito-asciidoc |   19 ++++++++++---------
 4 files changed, 33 insertions(+), 14 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -48,13 +48,13 @@ clean:
        rm -f *.xml *.html *.1 *.7 cg-*.txt cogito.txt
 %.html : %.txt
-       asciidoc -b xhtml11 -d manpage $<
+       asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
 %.1 %.7 : %.xml
        xmlto man $<
 %.xml : %.txt
-       asciidoc -b docbook -d manpage $<
+       asciidoc -b docbook -d manpage -f asciidoc.conf $<
 cogito.txt : make-cogito-asciidoc
        ./make-cogito-asciidoc > $@
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
new file mode 100644
--- /dev/null
+++ b/Documentation/asciidoc.conf
@@ -0,0 +1,18 @@
+## gitlink: macro
+# Usage: gitlink:command[manpage-section]
+# Note, {0} is the manpage section, while {target} is the command.
+# Show GIT link as: <command>(<section>); if section is defined, else just show
+# the command.
+<a href="{target}.html">{target}{0?({0})}</a>
diff --git a/Documentation/make-cg-asciidoc b/Documentation/make-cg-asciidoc
--- a/Documentation/make-cg-asciidoc
+++ b/Documentation/make-cg-asciidoc
@@ -40,7 +40,7 @@ CAPTION=$(echo "$HEADER" | head -n 1 | t
 # were referenced as "`cg-command`". This way references from cg-* combos in
 # code listings will be ignored.
 BODY=$(echo "$HEADER" | sed '0,/^$/d' \
-                     | sed 's/`\(cg-[a-z-]\+\)`/link:\1.html[\1]/')
+                     | sed 's/`\(cg-[a-z-]\+\)`/gitlink:\1[1]/')
@@ -108,6 +108,6 @@ $COPYRIGHT
-$COMMAND command is part of link:cogito.html[cogito(7)],
-a toolkit for managing link:git.html[git(1)] trees.
+$COMMAND command is part of gitlink:cogito[7],
+a toolkit for managing gitlink:git[7] trees.
diff --git a/Documentation/make-cogito-asciidoc 
--- a/Documentation/make-cogito-asciidoc
+++ b/Documentation/make-cogito-asciidoc
@@ -8,10 +8,11 @@ ADVANCED_COMMANDS="$(ls ../cg-admin-*)"
 HELPER_COMMANDS="$(ls ../cg-X*) $(ls ../*-id | grep -v git-)"
 # Shorthand for the link markup.
-       command="$1"
-       echo "link:$command.html['$command']"
+       section="$1"
+       command="$2"
+       echo "gitlink:$command[$section]"
 # Print description list entry.
@@ -28,7 +29,7 @@ print_command_info()
                usage=$(sed -n '/^USAGE=/,0s/.*cg-[^ ]*\(.*\)"/\1/p' < $command)
-               echo "link:$cmdname.html[$cmdname] $usage::"
+               echo "gitlink:$cmdname[] $usage::"
        echo "  $caption"
@@ -62,7 +63,7 @@ storage system. Amongst some of the note
 for branching, tagging and multiple backends for distributing repositories
 (local files, rsync, HTTP, ssh).
-'Cogito' is implemented as a series of 'bash(1)' scripts on top of $(link git)
+'Cogito' is implemented as a series of 'bash(1)' scripts on top of $(man 7 git)
 (a content-tracking filesystem) with the goal of providing an interface for
 working with the 'GIT' database in a manner similar to other SCM tools (like
 'CVS', 'BitKeeper' or 'Monotone').
@@ -107,21 +108,21 @@ $(print_command_listing $HELPER_COMMANDS
 Command Identifiers
-       Indicates a branch name added with the $(link cg-branch-add) command.
+       Indicates a branch name added with the $(man 1 cg-branch-add) command.
        Indicates a 'Cogito' command. The \`cg-\` prefix is optional.
-       Indicates a local file path or a URI. See $(link cg-branch-add) for a
+       Indicates a local file path or a URI. See $(man 1 cg-branch-add) for a
        list of supported URI schemes.
        Indicates an ID resolving to a commit. The following expressions can
        be used interchangably as IDs:
        - empty string, 'this' or 'HEAD' (current HEAD)
-       - branch name (as registered with $(link cg-branch-add))
-       - tag name (as registered with $(link cg-tag))
+       - branch name (as registered with $(man 1 cg-branch-add))
+       - tag name (as registered with $(man 1 cg-tag))
        - date string (as recognized by the 'date' tool)
        - shortcut object hash (shorted unambiguous hash lead)
        - commit object hash (as returned by 'commit-id')

Jonas Fonseca
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at

Reply via email to