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.
...
to
...
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.
+
+ifdef::backend-docbook[]
+[gitlink-inlinemacro]
+{target}{0?({0})}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[gitlink-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
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]/')
DESCRIPTION=
OPTIONS=
@@ -108,6 +108,6 @@ $COPYRIGHT
SEE ALSO
--------
-$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.
__END__
diff --git a/Documentation/make-cogito-asciidoc
b/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.
-link()
+man()
{
- 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()
;;
cg-*)
usage=$(sed -n '/^USAGE=/,0s/.*cg-[^ ]*\(.*\)"/\1/p' < $command)
- echo "link:$cmdname.html[$cmdname] $usage::"
+ echo "gitlink:$cmdname[] $usage::"
;;
esac
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
-------------------
BRANCH_NAME::
- 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.
COMMAND::
Indicates a 'Cogito' command. The \`cg-\` prefix is optional.
LOCATION::
- 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.
COMMIT_ID, FROM_ID, TO_ID, BASE_COMMIT::
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 http://vger.kernel.org/majordomo-info.html
