{"thread":{"id":"6908","subject":"[RFC PATCH] Add a stgit Documentation directory inspired by the git one.","startedAt":"2007-02-21T22:53:01Z","lastAt":"2007-02-21T22:53:01Z","messageCount":1,"participants":["Yann Dirson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"35209","messageId":"20070221224531.7956.4335.stgit@gandelf.nowhere.earth","threadId":"6908","inReplyTo":null,"subject":"[RFC PATCH] Add a stgit Documentation directory inspired by the git one.","fromName":"Yann Dirson","fromEmail":"ydirson@altern.org","sentAt":"2007-02-21T22:53:01Z","receivedAt":"2007-02-21T22:53:01Z","isPatch":true,"sender":{"key":"ydirson@altern.org","avatar":"https://avatars.githubusercontent.com/u/1190950?v=4"},"body":"Signed-off-by: Yann Dirson <ydirson@altern.org>\n---\n\n[Please don't apply yet - this is a proof of concept to gather\nfeedback before I invest more time in this]\n\nThis is an early sketch of a Documentation directory for StGIT.  I\nmostly took the Documentation directory from Git and adapted it\nslightly.\n\nIt is not 100% suited to stgit yet, because 1) unlike git, the StGIT\nmain command is named \"stg\" and not \"stgit\", and 2) the various\ncommands are not available individually as stg-<name>.\n\nBecause of manpage namespace consideration, the manpages will still\nhave to be named stg-*.1 of something similar, so the issue left is\nhow to handle the presentation, in docbook/man and in html.  I had a\ntry at a simple adaptation of the gitlink macro (as stglink), but it\nwill surely need tuning (eg. we'll probably want to avoid passing the\nman section as argument, it will be a constant).\n\n\n Documentation/Makefile          |   62 ++++++++++++++++++++++++++++++++\n Documentation/asciidoc.conf     |   52 +++++++++++++++++++++++++++\n Documentation/build-docdep.perl |   50 ++++++++++++++++++++++++++\n Documentation/callouts.xsl      |   30 ++++++++++++++++\n Documentation/stg-new.txt       |   43 ++++++++++++++++++++++\n Documentation/stg.txt           |   75 +++++++++++++++++++++++++++++++++++++++\n 6 files changed, 312 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nnew file mode 100644\nindex 0000000..670bfd3\n--- /dev/null\n+++ b/Documentation/Makefile\n@@ -0,0 +1,62 @@\n+MAN1_TXT=$(wildcard stg-*.txt)\n+MAN7_TXT=stg.txt\n+\n+DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))\n+\n+DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))\n+DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))\n+\n+prefix?=$(HOME)\n+mandir?=$(prefix)/man\n+man1dir=$(mandir)/man1\n+man7dir=$(mandir)/man7\n+# DESTDIR=\n+\n+ASCIIDOC=asciidoc\n+ASCIIDOC_EXTRA =\n+INSTALL?=install\n+\n+#\n+# Please note that there is a minor bug in asciidoc.\n+# The version after 6.0.3 _will_ include the patch found here:\n+#   http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2\n+#\n+# Until that version is released you may have to apply the patch\n+# yourself - yes, all 6 characters of it!\n+#\n+\n+all: html man\n+\n+html: $(DOC_HTML)\n+\n+$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN7): asciidoc.conf\n+\n+man: man1 man7\n+man1: $(DOC_MAN1)\n+man7: $(DOC_MAN7)\n+\n+install: man\n+\t$(INSTALL) -d -m755 $(DESTDIR)$(man1dir) $(DESTDIR)$(man7dir)\n+\t$(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir)\n+\t$(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir)\n+#\n+# Determine \"include::\" file references in asciidoc files.\n+#\n+doc.dep : $(wildcard *.txt) build-docdep.perl\n+\trm -f $@+ $@\n+\tperl ./build-docdep.perl >$@+\n+\tmv $@+ $@\n+\n+-include doc.dep\n+\n+clean:\n+\trm -f *.xml *.html *.1 *.7 doc.dep\n+\n+%.html : %.txt\n+\t$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $<\n+\n+%.1 %.7 : %.xml\n+\txmlto -m callouts.xsl man $<\n+\n+%.xml : %.txt\n+\t$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $<\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nnew file mode 100644\nindex 0000000..e019a0e\n--- /dev/null\n+++ b/Documentation/asciidoc.conf\n@@ -0,0 +1,52 @@\n+## gitlink: macro\n+#\n+# Usage: gitlink:command[manpage-section]\n+#\n+# Note, {0} is the manpage section, while {target} is the command.\n+#\n+# Show GIT link as: <command>(<section>); if section is defined, else just show\n+# the command.\n+\n+[attributes]\n+caret=^\n+startsb=&#91;\n+endsb=&#93;\n+tilde=&#126;\n+\n+ifdef::backend-docbook[]\n+[gitlink-inlinemacro]\n+{0%{target}}\n+{0#<citerefentry>}\n+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n+{0#</citerefentry>}\n+endif::backend-docbook[]\n+\n+ifdef::backend-docbook[]\n+# \"unbreak\" docbook-xsl v1.68 for manpages. v1.69 works with or without this.\n+[listingblock]\n+<example><title>{title}</title>\n+<literallayout>\n+|\n+</literallayout>\n+{title#}</example>\n+endif::backend-docbook[]\n+\n+ifdef::backend-xhtml11[]\n+[gitlink-inlinemacro]\n+<a href=\"{target}.html\">{target}{0?({0})}</a>\n+endif::backend-xhtml11[]\n+\n+# stglink\n+\n+ifdef::backend-docbook[]\n+[stglink-inlinemacro]\n+{0%{target}}\n+{0#<citerefentry>}\n+{0#<refentrytitle>stg-{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n+{0#</citerefentry>}\n+endif::backend-docbook[]\n+\n+ifdef::backend-xhtml11[]\n+[stglink-inlinemacro]\n+<a href=\"stg-{target}.html\">{target}{0?({0})}</a>\n+endif::backend-xhtml11[]\ndiff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl\nnew file mode 100755\nindex 0000000..489389c\n--- /dev/null\n+++ b/Documentation/build-docdep.perl\n@@ -0,0 +1,50 @@\n+#!/usr/bin/perl\n+\n+my %include = ();\n+my %included = ();\n+\n+for my $text (<*.txt>) {\n+    open I, '<', $text || die \"cannot read: $text\";\n+    while (<I>) {\n+\tif (/^include::/) {\n+\t    chomp;\n+\t    s/^include::\\s*//;\n+\t    s/\\[\\]//;\n+\t    $include{$text}{$_} = 1;\n+\t    $included{$_} = 1;\n+\t}\n+    }\n+    close I;\n+}\n+\n+# Do we care about chained includes???\n+my $changed = 1;\n+while ($changed) {\n+    $changed = 0;\n+    while (my ($text, $included) = each %include) {\n+\tfor my $i (keys %$included) {\n+\t    # $text has include::$i; if $i includes $j\n+\t    # $text indirectly includes $j.\n+\t    if (exists $include{$i}) {\n+\t\tfor my $j (keys %{$include{$i}}) {\n+\t\t    if (!exists $include{$text}{$j}) {\n+\t\t\t$include{$text}{$j} = 1;\n+\t\t\t$included{$j} = 1;\n+\t\t\t$changed = 1;\n+\t\t    }\n+\t\t}\n+\t    }\n+\t}\n+    }\n+}\n+\n+while (my ($text, $included) = each %include) {\n+    if (! exists $included{$text} &&\n+\t(my $base = $text) =~ s/\\.txt$//) {\n+\tmy ($suffix) = '1';\n+\tif ($base eq 'git') {\n+\t    $suffix = '7'; # yuck...\n+\t}\n+\tprint \"$base.html $base.$suffix : \", join(\" \", keys %$included), \"\\n\";\n+    }\n+}\ndiff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl\nnew file mode 100644\nindex 0000000..6a361a2\n--- /dev/null\n+++ b/Documentation/callouts.xsl\n@@ -0,0 +1,30 @@\n+<!-- callout.xsl: converts asciidoc callouts to man page format -->\n+<xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" version=\"1.0\">\n+<xsl:template match=\"co\">\n+\t<xsl:value-of select=\"concat('\\fB(',substring-after(@id,'-'),')\\fR')\"/>\n+</xsl:template>\n+<xsl:template match=\"calloutlist\">\n+\t<xsl:text>.sp&#10;</xsl:text>\n+\t<xsl:apply-templates/>\n+\t<xsl:text>&#10;</xsl:text>\n+</xsl:template>\n+<xsl:template match=\"callout\">\n+\t<xsl:value-of select=\"concat('\\fB',substring-after(@arearefs,'-'),'. \\fR')\"/>\n+\t<xsl:apply-templates/>\n+\t<xsl:text>.br&#10;</xsl:text>\n+</xsl:template>\n+\n+<!-- sorry, this is not about callouts, but attempts to work around\n+ spurious .sp at the tail of the line docbook stylesheets seem to add -->\n+<xsl:template match=\"simpara\">\n+  <xsl:variable name=\"content\">\n+    <xsl:apply-templates/>\n+  </xsl:variable>\n+  <xsl:value-of select=\"normalize-space($content)\"/>\n+  <xsl:if test=\"not(ancestor::authorblurb) and\n+                not(ancestor::personblurb)\">\n+    <xsl:text>&#10;&#10;</xsl:text>\n+  </xsl:if>\n+</xsl:template>\n+\n+</xsl:stylesheet>\ndiff --git a/Documentation/stg-new.txt b/Documentation/stg-new.txt\nnew file mode 100644\nindex 0000000..225ce3d\n--- /dev/null\n+++ b/Documentation/stg-new.txt\n@@ -0,0 +1,43 @@\n+stg-new(1)\n+==========\n+\n+NAME\n+----\n+stg-new - create a new patch\n+\n+SYNOPSIS\n+--------\n+stg new [OPTIONS] <name>\n+\n+DESCRIPTION\n+-----------\n+\n+'stg new' creates a new patch with the given <name> on the current\n+stack.  The new patch is created on top of the currently applied\n+patches, and is made the new top of the stack.\n+\n+An editor will be launched to edit the commit message to be used for\n+the patch, unless the '-m' flag already specified one.\n+\n+The message and other GIT commit attributes can be modified later\n+using stglink:refresh[1].\n+\n+OPTIONS\n+-------\n+<name>::\n+\tThe short name that will be used as to identify the patch in\n+\tother StGIT commands.  Must be unique in the stack.  May only\n+\tcontain alphanumeric characters, dashes and underscores.\n+\n+--message=<message>::\n+-m <message>::\n+\tUse <message> as the patch description.\n+\n+--showpatch::\n+-s::\n+\tShow the patch content in the editor buffer.  This flag does\n+\tnothing if '-m' is also specified.\n+\n+StGIT\n+-----\n+Part of the StGIT suite - see gitlink:stg[7]\ndiff --git a/Documentation/stg.txt b/Documentation/stg.txt\nnew file mode 100644\nindex 0000000..d5a61b2\n--- /dev/null\n+++ b/Documentation/stg.txt\n@@ -0,0 +1,75 @@\n+stg(7)\n+======\n+\n+NAME\n+----\n+stg - manage stacks of patches using the GIT content tracker\n+\n+SYNOPSIS\n+--------\n+[verse]\n+'stg' [--version] [--help] <command> [OPTIONS] [ARGS]\n+\n+DESCRIPTION\n+-----------\n+\n+StGIT (Stacked GIT) is a Python application providing similar\n+functionality to Quilt (i.e. pushing/popping patches to/from a stack)\n+on top of GIT. These operations are performed using GIT commands and\n+the patches are stored as GIT commit objects, allowing easy merging of\n+the StGIT patches into other repositories using standard GIT\n+functionality.\n+\n+OPTIONS\n+-------\n+\n+--version::\n+\tPrints the StGIT suite version that the 'stg' program came\n+\tfrom, as well as version of other components used, such as GIT\n+\tand Python.\n+\n+--help::\n+\tPrints the synopsis and a list of all commands.  If a git\n+\tcommand is given this option will display the specific help\n+\tfor that command.\n+\n+STGIT COMMANDS\n+--------------\n+\n+We divide StGIT commands in thematic groups, according to the primary\n+type of object they create or change.\n+\n+Generic commands\n+----------------\n+\n+Informational commands not touching the repository.\n+\n+Repository commands\n+-------------------\n+\n+stglink:clone[1]::\n+\tclone a remote repository into local storage\n+\n+Stack commands\n+--------------\n+\n+stglink:branch[1]::\n+\tmanage patch series\n+\n+Patch commands\n+--------------\n+\n+stglink:new[1]::\n+\tcreate a new patch and make it the topmost one\n+\n+Working-copy commands\n+---------------------\n+\n+stglink:status[1]::\n+\tshow the tree status\n+\n+CONFIGURATION MECHANISM\n+-----------------------\n+\n+Starting with 0.12, StGIT uses the same configuration mechanism as\n+GIT.  See gitlink:git[7] for more details.\n"}]}