Signed-off-by: Yann Dirson <ydirson@xxxxxxxxxx> --- [Please don't apply yet - this is a proof of concept to gather feedback before I invest more time in this] This is an early sketch of a Documentation directory for StGIT. I mostly took the Documentation directory from Git and adapted it slightly. It is not 100% suited to stgit yet, because 1) unlike git, the StGIT main command is named "stg" and not "stgit", and 2) the various commands are not available individually as stg-<name>. Because of manpage namespace consideration, the manpages will still have to be named stg-*.1 of something similar, so the issue left is how to handle the presentation, in docbook/man and in html. I had a try at a simple adaptation of the gitlink macro (as stglink), but it will surely need tuning (eg. we'll probably want to avoid passing the man section as argument, it will be a constant). Documentation/Makefile | 62 ++++++++++++++++++++++++++++++++ Documentation/asciidoc.conf | 52 +++++++++++++++++++++++++++ Documentation/build-docdep.perl | 50 ++++++++++++++++++++++++++ Documentation/callouts.xsl | 30 ++++++++++++++++ Documentation/stg-new.txt | 43 ++++++++++++++++++++++ Documentation/stg.txt | 75 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 312 insertions(+), 0 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000..670bfd3 --- /dev/null +++ b/Documentation/Makefile @@ -0,0 +1,62 @@ +MAN1_TXT=$(wildcard stg-*.txt) +MAN7_TXT=stg.txt + +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) + +DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) +DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) + +prefix?=$(HOME) +mandir?=$(prefix)/man +man1dir=$(mandir)/man1 +man7dir=$(mandir)/man7 +# DESTDIR= + +ASCIIDOC=asciidoc +ASCIIDOC_EXTRA = +INSTALL?=install + +# +# Please note that there is a minor bug in asciidoc. +# The version after 6.0.3 _will_ include the patch found here: +# http://marc.theaimsgroup.com/?l=git&m=111558757202243&w=2 +# +# Until that version is released you may have to apply the patch +# yourself - yes, all 6 characters of it! +# + +all: html man + +html: $(DOC_HTML) + +$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN7): asciidoc.conf + +man: man1 man7 +man1: $(DOC_MAN1) +man7: $(DOC_MAN7) + +install: man + $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) $(DESTDIR)$(man7dir) + $(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir) + $(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir) +# +# Determine "include::" file references in asciidoc files. +# +doc.dep : $(wildcard *.txt) build-docdep.perl + rm -f $@+ $@ + perl ./build-docdep.perl >$@+ + mv $@+ $@ + +-include doc.dep + +clean: + rm -f *.xml *.html *.1 *.7 doc.dep + +%.html : %.txt + $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $< + +%.1 %.7 : %.xml + xmlto -m callouts.xsl man $< + +%.xml : %.txt + $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $< diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf new file mode 100644 index 0000000..e019a0e --- /dev/null +++ b/Documentation/asciidoc.conf @@ -0,0 +1,52 @@ +## 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. + +[attributes] +caret=^ +startsb=[ +endsb=] +tilde=~ + +ifdef::backend-docbook[] +[gitlink-inlinemacro] +{0%{target}} +{0#<citerefentry>} +{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} +{0#</citerefentry>} +endif::backend-docbook[] + +ifdef::backend-docbook[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +[listingblock] +<example><title>{title}</title> +<literallayout> +| +</literallayout> +{title#}</example> +endif::backend-docbook[] + +ifdef::backend-xhtml11[] +[gitlink-inlinemacro] +<a href="{target}.html">{target}{0?({0})}</a> +endif::backend-xhtml11[] + +# stglink + +ifdef::backend-docbook[] +[stglink-inlinemacro] +{0%{target}} +{0#<citerefentry>} +{0#<refentrytitle>stg-{target}</refentrytitle><manvolnum>{0}</manvolnum>} +{0#</citerefentry>} +endif::backend-docbook[] + +ifdef::backend-xhtml11[] +[stglink-inlinemacro] +<a href="stg-{target}.html">{target}{0?({0})}</a> +endif::backend-xhtml11[] diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl new file mode 100755 index 0000000..489389c --- /dev/null +++ b/Documentation/build-docdep.perl @@ -0,0 +1,50 @@ +#!/usr/bin/perl + +my %include = (); +my %included = (); + +for my $text (<*.txt>) { + open I, '<', $text || die "cannot read: $text"; + while (<I>) { + if (/^include::/) { + chomp; + s/^include::\s*//; + s/\[\]//; + $include{$text}{$_} = 1; + $included{$_} = 1; + } + } + close I; +} + +# Do we care about chained includes??? +my $changed = 1; +while ($changed) { + $changed = 0; + while (my ($text, $included) = each %include) { + for my $i (keys %$included) { + # $text has include::$i; if $i includes $j + # $text indirectly includes $j. + if (exists $include{$i}) { + for my $j (keys %{$include{$i}}) { + if (!exists $include{$text}{$j}) { + $include{$text}{$j} = 1; + $included{$j} = 1; + $changed = 1; + } + } + } + } + } +} + +while (my ($text, $included) = each %include) { + if (! exists $included{$text} && + (my $base = $text) =~ s/\.txt$//) { + my ($suffix) = '1'; + if ($base eq 'git') { + $suffix = '7'; # yuck... + } + print "$base.html $base.$suffix : ", join(" ", keys %$included), "\n"; + } +} diff --git a/Documentation/callouts.xsl b/Documentation/callouts.xsl new file mode 100644 index 0000000..6a361a2 --- /dev/null +++ b/Documentation/callouts.xsl @@ -0,0 +1,30 @@ +<!-- callout.xsl: converts asciidoc callouts to man page format --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0"> +<xsl:template match="co"> + <xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:text>.sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/> + <xsl:apply-templates/> + <xsl:text>.br </xsl:text> +</xsl:template> + +<!-- sorry, this is not about callouts, but attempts to work around + spurious .sp at the tail of the line docbook stylesheets seem to add --> +<xsl:template match="simpara"> + <xsl:variable name="content"> + <xsl:apply-templates/> + </xsl:variable> + <xsl:value-of select="normalize-space($content)"/> + <xsl:if test="not(ancestor::authorblurb) and + not(ancestor::personblurb)"> + <xsl:text> </xsl:text> + </xsl:if> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/stg-new.txt b/Documentation/stg-new.txt new file mode 100644 index 0000000..225ce3d --- /dev/null +++ b/Documentation/stg-new.txt @@ -0,0 +1,43 @@ +stg-new(1) +========== + +NAME +---- +stg-new - create a new patch + +SYNOPSIS +-------- +stg new [OPTIONS] <name> + +DESCRIPTION +----------- + +'stg new' creates a new patch with the given <name> on the current +stack. The new patch is created on top of the currently applied +patches, and is made the new top of the stack. + +An editor will be launched to edit the commit message to be used for +the patch, unless the '-m' flag already specified one. + +The message and other GIT commit attributes can be modified later +using stglink:refresh[1]. + +OPTIONS +------- +<name>:: + The short name that will be used as to identify the patch in + other StGIT commands. Must be unique in the stack. May only + contain alphanumeric characters, dashes and underscores. + +--message=<message>:: +-m <message>:: + Use <message> as the patch description. + +--showpatch:: +-s:: + Show the patch content in the editor buffer. This flag does + nothing if '-m' is also specified. + +StGIT +----- +Part of the StGIT suite - see gitlink:stg[7] diff --git a/Documentation/stg.txt b/Documentation/stg.txt new file mode 100644 index 0000000..d5a61b2 --- /dev/null +++ b/Documentation/stg.txt @@ -0,0 +1,75 @@ +stg(7) +====== + +NAME +---- +stg - manage stacks of patches using the GIT content tracker + +SYNOPSIS +-------- +[verse] +'stg' [--version] [--help] <command> [OPTIONS] [ARGS] + +DESCRIPTION +----------- + +StGIT (Stacked GIT) is a Python application providing similar +functionality to Quilt (i.e. pushing/popping patches to/from a stack) +on top of GIT. These operations are performed using GIT commands and +the patches are stored as GIT commit objects, allowing easy merging of +the StGIT patches into other repositories using standard GIT +functionality. + +OPTIONS +------- + +--version:: + Prints the StGIT suite version that the 'stg' program came + from, as well as version of other components used, such as GIT + and Python. + +--help:: + Prints the synopsis and a list of all commands. If a git + command is given this option will display the specific help + for that command. + +STGIT COMMANDS +-------------- + +We divide StGIT commands in thematic groups, according to the primary +type of object they create or change. + +Generic commands +---------------- + +Informational commands not touching the repository. + +Repository commands +------------------- + +stglink:clone[1]:: + clone a remote repository into local storage + +Stack commands +-------------- + +stglink:branch[1]:: + manage patch series + +Patch commands +-------------- + +stglink:new[1]:: + create a new patch and make it the topmost one + +Working-copy commands +--------------------- + +stglink:status[1]:: + show the tree status + +CONFIGURATION MECHANISM +----------------------- + +Starting with 0.12, StGIT uses the same configuration mechanism as +GIT. See gitlink:git[7] for more details. - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html