From 473590da911c99dfa9554ab40e73e9f364dd5ecb Mon Sep 17 00:00:00 2001 From: Peter Grayson Date: Fri, 24 Apr 2020 17:11:00 -0400 Subject: [PATCH] Overhaul documentation build system The documentation build system (Documentation/Makefile, etc.) was originally based on Git's documentation system c.a. 2007. Since then, Git has made many updates to their build system while StGit's has remained mostly static. - More robust Makefile - Quiet output by default - More/better variables for executables - Better dependency tracking - info target (stgitman.info) - Repaired links to git man pages - Repaired relative links for stgit commands - StGit version in man pages - asciidoctor support (make USE_ASCIIDOCTOR=1) Signed-off-by: Peter Grayson --- Documentation/.gitignore | 7 +- Documentation/Makefile | 308 ++++++++++++++++++++---- Documentation/asciidoc.conf | 74 +++++- Documentation/asciidoctor-extensions.rb | 112 +++++++++ Documentation/cat-texi.perl | 46 ++++ Documentation/docbook-xsl.css | 296 +++++++++++++++++++++++ Documentation/docbook.xsl | 8 + Documentation/fix-texi.perl | 15 ++ Documentation/manpage-1.72.xsl | 14 ++ Documentation/manpage-base-url.xsl.in | 10 + Documentation/manpage-base.xsl | 35 +++ Documentation/manpage-bold-literal.xsl | 18 ++ Documentation/manpage-normal.xsl | 13 + Documentation/manpage-quote-apos.xsl | 16 ++ Documentation/manpage-suppress-sp.xsl | 21 ++ Documentation/manpage.xsl | 3 + Documentation/stg.txt | 2 +- Documentation/texi.xsl | 26 ++ Documentation/tutorial.conf | 18 ++ Documentation/tutorial.txt | 8 +- MANIFEST.in | 7 +- build.py | 8 +- 22 files changed, 992 insertions(+), 73 deletions(-) create mode 100644 Documentation/asciidoctor-extensions.rb create mode 100755 Documentation/cat-texi.perl create mode 100644 Documentation/docbook-xsl.css create mode 100644 Documentation/docbook.xsl create mode 100755 Documentation/fix-texi.perl create mode 100644 Documentation/manpage-1.72.xsl create mode 100644 Documentation/manpage-base-url.xsl.in create mode 100644 Documentation/manpage-base.xsl create mode 100644 Documentation/manpage-bold-literal.xsl create mode 100644 Documentation/manpage-normal.xsl create mode 100644 Documentation/manpage-quote-apos.xsl create mode 100644 Documentation/manpage-suppress-sp.xsl create mode 100644 Documentation/manpage.xsl create mode 100644 Documentation/texi.xsl diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 6d9c822e..0f1eddfa 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,7 +1,10 @@ +*.xml *.html -*.pdf *.[1-9] -*.xml +*.texi +*.pdf stg-*.txt doc.dep command-list.txt +manpage-base-url.xsl +STGIT-ASCIIDOCFLAGS diff --git a/Documentation/Makefile b/Documentation/Makefile index 07b34843..136cf4d9 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,90 +1,296 @@ -COMMANDS = $(shell $(PYTHON) ../build.py --commands) -COMMANDS_TXT = $(patsubst %,stg-%.txt,$(COMMANDS)) +# Guard against environment variables +MAN1_TXT = +MAN5_TXT = +MAN7_TXT = +TECH_DOCS = +ARTICLES = +SP_ARTICLES = +OBSOLETE_HTML = -MAN1_TXT= stg.txt $(COMMANDS_TXT) +STGIT_ALL_PY = $(shell find ../stgit -name '*.py') +STG_COMMANDS = $(shell $(PYTHON) ../build.py --commands) +STG_COMMANDS_TXT = $(patsubst %,stg-%.txt,$(STG_COMMANDS)) +STGIT_VERSION = $(shell $(PYTHON) ../build.py --stgit-version) + +MAN1_TXT += stg.txt +MAN1_TXT += $(STG_COMMANDS_TXT) + +ifdef MAN_FILTER +MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) +else +MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) +MAN_FILTER = $(MAN_TXT) +endif + +MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) +MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT)) -ARTICLES = tutorial +ARTICLES += tutorial -DOC_HTML += $(patsubst %,%.html,$(ARTICLES)) -DOC_PDF += $(patsubst %,%.pdf,$(ARTICLES)) +ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) +HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML) +DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML)) -DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) +DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT))) +DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT))) +DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT))) -prefix?=$(HOME)/.local -htmldir?=$(prefix)/share/doc/stgit -mandir?=$(prefix)/share/man -man1dir=$(mandir)/man1 -# DESTDIR= +prefix ?= $(HOME)/.local +bindir ?= $(prefix)/bin +htmldir ?= $(prefix)/share/doc/stgit +infodir ?= $(prefix)/share/info +pdfdir ?= $(prefix)/share/doc/stgit +mandir ?= $(prefix)/share/man +man1dir = $(mandir)/man1 +man5dir = $(mandir)/man5 +man7dir = $(mandir)/man7 +# DESTDIR = -ASCIIDOC=asciidoc --unsafe +ASCIIDOC = asciidoc ASCIIDOC_EXTRA = -INSTALL?=install +ASCIIDOC_HTML = xhtml11 +ASCIIDOC_DOCBOOK = docbook +ASCIIDOC_CONF = -f asciidoc.conf +ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ + -amanversion=$(STGIT_VERSION) \ + -amanmanual='StGit Manual' -amansource='StGit' +TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) +TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) +MANPAGE_XSL = manpage-normal.xsl +XMLTO = xmlto +XMLTO_EXTRA = +INSTALL ?= install +RM ?= rm -f + +MAKEINFO = makeinfo +INSTALL_INFO = install-info +DOCBOOK2X_TEXI = docbook2x-texi +DBLATEX = dblatex +ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex +DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty +ifndef PERL_PATH + PERL_PATH = /usr/bin/perl +endif # -# 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 +# For docbook-xsl ... +# -1.68.1, no extra settings are needed? +# 1.69.0, set ASCIIDOC_ROFF? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, set ASCIIDOC_ROFF? +# 1.72.0, set DOCBOOK_XSL_172. +# 1.73.0-, no extra settings are needed # -# Until that version is released you may have to apply the patch -# yourself - yes, all 6 characters of it! + +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a git-asciidoc-no-roff +MANPAGE_XSL = manpage-1.72.xsl +else + ifndef ASCIIDOC_ROFF + # docbook-xsl after 1.72 needs the regular XSL, but will not + # pass-thru raw roff codes from asciidoc.conf, so turn them off. + ASCIIDOC_EXTRA += -a git-asciidoc-no-roff + endif +endif +ifndef NO_MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif + +# Newer DocBook stylesheet emits warning cruft in the output when +# this is not set, and if set it shows an absolute link. Older +# stylesheets simply ignore this parameter. # +# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/ +# or similar. +ifndef MAN_BASE_URL +MAN_BASE_URL = file://$(htmldir)/ +endif +XMLTO_EXTRA += -m manpage-base-url.xsl + +# If your target system uses GNU groff, it may try to render +# apostrophes as a "pretty" apostrophe using unicode. This breaks +# cut&paste, so you should set GNU_ROFF to force them to be ASCII +# apostrophes. Unfortunately does not work with non-GNU roff. +ifdef GNU_ROFF +XMLTO_EXTRA += -m manpage-quote-apos.xsl +endif + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_CONF = +ASCIIDOC_HTML = xhtml5 +ASCIIDOC_DOCBOOK = docbook5 +ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +DBLATEX_COMMON = +XMLTO_EXTRA += --skip-validation +XMLTO_EXTRA += -x manpage.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir +QUIET_SUBDIR1 = + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifndef V + QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; + QUIET_XMLTO = @echo ' ' XMLTO $@; + QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; + QUIET_MAKEINFO = @echo ' ' MAKEINFO $@; + QUIET_DBLATEX = @echo ' ' DBLATEX $@; + QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; + QUIET_GEN = @echo ' ' GEN $@; + QUIET_LINT = @echo ' ' LINT $@; + QUIET_STDERR = 2> /dev/null + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif all: html man html: $(DOC_HTML) -pdf: $(DOC_PDF) -$(DOC_HTML) $(DOC_MAN1): asciidoc.conf - -man: man1 +man: man1 man5 man7 man1: $(DOC_MAN1) -install: man - $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) - $(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir) +man5: $(DOC_MAN5) +man7: $(DOC_MAN7) + +info: stgitman.info + +pdf: tutorial.pdf + +install: install-man + +install-man: man + $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir) + $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir) + +install-info: info + $(INSTALL) -d -m 755 $(DESTDIR)$(infodir) + $(INSTALL) -m 644 stgitman.info $(DESTDIR)$(infodir) + if test -r $(DESTDIR)$(infodir)/dir; then \ + $(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) stgitman.info ;\ + else \ + echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \ + fi + +install-pdf: pdf + $(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir) + $(INSTALL) -m 644 tutorial.pdf $(DESTDIR)$(pdfdir) install-html: html - $(INSTALL) -d -m755 $(DESTDIR)$(htmldir) - $(INSTALL) -m644 $(DOC_HTML) $(DESTDIR)$(htmldir) + $(INSTALL) -d -m 755 $(DESTDIR)$(htmldir) + $(INSTALL) -m 644 $(DOC_HTML) $(DESTDIR)$(htmldir) + +$(DOC_HTML) $(DOC_MAN1): asciidoc.conf + # # Determine "include::" file references in asciidoc files. # doc.dep : $(wildcard *.txt) build-docdep.perl - rm -f $@+ $@ - perl ./build-docdep.perl >$@+ + $(QUIET_GEN)$(RM) $@+ $@ && \ + $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ mv $@+ $@ -include doc.dep +TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) + +STGIT-ASCIIDOCFLAGS: FORCE + @FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \ + if test x"$$FLAGS" != x"`cat STGIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \ + echo >&2 " * new asciidoc flags"; \ + echo "$$FLAGS" >STGIT-ASCIIDOCFLAGS; \ + fi + clean: - rm -f *.xml *.html *.pdf *.1 doc.dep $(COMMANDS_TXT) command-list.txt + $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 + $(RM) *.texi *.texi+ *.texi++ stgitman.info + $(RM) *.pdf + $(RM) doc.dep + $(RM) manpage-base-url.xsl + $(RM) STGIT-ASCIIDOCFLAGS + $(RM) $(STG_COMMANDS_TXT) command-list.txt -build-txt: $(COMMANDS_TXT) command-list.txt +$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb STGIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_HTML) -d manpage -o $@+ $< && \ + mv $@+ $@ + +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb STGIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_HTML) -o $@+ $< && \ + mv $@+ $@ -ALL_PY = $(shell find ../stgit -name '*.py') +manpage-base-url.xsl: manpage-base-url.xsl.in + $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ -$(COMMANDS_TXT): $(ALL_PY) - $(PYTHON) ../build.py --asciidoc $(basename $(subst stg-,,$@)) > $@ +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb STGIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_XML) -d manpage -o $@+ $< && \ + mv $@+ $@ + +tutorial.xml: tutorial.txt tutorial.conf asciidoctor-extensions.rb STGIT-ASCIIDOCFLAGS + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(TXT_TO_XML) -d article -o $@+ $< && \ + mv $@+ $@ + +tutorial.pdf: tutorial.xml + $(QUIET_DBLATEX)$(RM) $@+ $@ && \ + $(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \ + mv $@+ $@ + +stgitman.texi: $(MAN_XML) cat-texi.perl texi.xsl + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + ($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \ + $(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \ + rm $(xml)+ &&) true) > $@++ && \ + $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \ + rm $@++ && \ + mv $@+ $@ + +stgitman.info: stgitman.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi + +$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \ + mv $@+ $@ -command-list.txt: $(ALL_PY) - $(PYTHON) ../build.py --cmd-list > $@ +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -a toc $*.txt -%.html : %.txt - $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $< +print-man1: + @for i in $(MAN1_TXT); do echo $$i; done -%.1 : %.xml - xmlto -m callouts.xsl man $< +.PHONY: FORCE -%.xml : %.txt - $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $< +$(STG_COMMANDS_TXT): $(STGIT_ALL_PY) + $(QUIET_GEN)$(PYTHON) ../build.py --asciidoc $(basename $(subst stg-,,$@)) > $@ -%.pdf: %.xml - xmlto pdf $< +command-list.txt: $(STGIT_ALL_PY) + $(QUIET_GEN)$(PYTHON) ../build.py --cmd-list > $@ -# special formatting rules -tutorial.html : %.html : %.txt - $(ASCIIDOC) -b xhtml11 -d article -a toc -f tutorial.conf \ - $(ASCIIDOC_EXTRA) $< -tutorial.xml : %.xml : %.txt - $(ASCIIDOC) -b docbook -d article -f tutorial.conf $< +build-txt: command-list.txt FORCE diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 7afcf6f5..098017fb 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -1,18 +1,45 @@ +## linkgit: macro +# +# Usage: linkgit:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show Git link as: (
); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?Plinkgit):(?P\S*?)\[(?P.*?)\]= +(?Plinkman):(?P\w+)\[(?P\d+)]= +(?Plinkstgsub):(?P\w+)\[]= +(?Plinkstg):(?P\w+)\[]= + [attributes] asterisk=* plus=+ caret=^ startsb=[ endsb=] +backslash=\ tilde=~ +apostrophe=' +backtick=` +litdd=-- ifdef::backend-docbook[] -ifndef::docbook-xsl-172[] +[linkgit-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +endif::backend-docbook[] + +ifdef::backend-docbook[] +ifndef::stgit-asciidoc-no-roff[] # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. # v1.72 breaks with this because it replaces dots not in roff requests. [listingblock] {title} - + ifdef::doctype-manpage[] .ft C endif::doctype-manpage[] @@ -22,7 +49,28 @@ ifdef::doctype-manpage[] endif::doctype-manpage[] {title#} -endif::docbook-xsl-172[] +endif::stgit-asciidoc-no-roff[] + +ifdef::stgit-asciidoc-no-roff[] +ifdef::doctype-manpage[] +# The following two small workarounds insert a simple paragraph after screen +[listingblock] +{title} + +| + +{title#} + +[verseblock] +{title} +{title%} +{title#} +| + +{title#} +{title%} +endif::doctype-manpage[] +endif::stgit-asciidoc-no-roff[] endif::backend-docbook[] ifdef::doctype-manpage[] @@ -33,9 +81,9 @@ template::[header-declarations] {mantitle} {manvolnum} -StGit -{stgit_version} -StGit Manual +{mansource} +{manversion} +{manmanual} {manname} @@ -44,6 +92,14 @@ template::[header-declarations] endif::backend-docbook[] endif::doctype-manpage[] +ifdef::backend-xhtml11[] +[attributes] +git-relative-html-prefix= +[linkgit-inlinemacro] +# {target}{0?({0})} +{target}{0?({0})} +endif::backend-xhtml11[] + ## linkman: macro # # Usage: linkman:command[manpage-section] @@ -100,9 +156,3 @@ ifdef::backend-xhtml11[] [linkstgsub-inlinemacro] {target} endif::backend-xhtml11[] - -[macros] -# regexen to match macro templates above -(?Plinkman):(?P\w+)\[(?P\d+)]= -(?Plinkstgsub):(?P\w+)\[]= -(?Plinkstg):(?P\w+)\[]= diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb new file mode 100644 index 00000000..4c00f27e --- /dev/null +++ b/Documentation/asciidoctor-extensions.rb @@ -0,0 +1,112 @@ +require 'asciidoctor' +require 'asciidoctor/extensions' + +module StGit + module Documentation + class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor + use_dsl + + named :chrome + + def process(parent, target, attrs) + gitscm = 'https://git-scm.com/docs/' + if parent.document.doctype == 'book' \ + or parent.document.doctype == 'article' + "" \ + "#{target}(#{attrs[1]})" + elsif parent.document.basebackend? 'html' + %(#{target}(#{attrs[1]})) + elsif parent.document.basebackend? 'docbook' + "\n" \ + "#{target}" \ + "#{attrs[1]}\n" \ + "" + end + end + end + + class LinkManProcessor < Asciidoctor::Extensions::InlineMacroProcessor + use_dsl + + named :chrome + + def process(parent, target, attrs) + if parent.document.doctype == 'book' \ + or parent.document.doctype == 'article' + "#{target}(#{attrs[1]})" + elsif parent.document.basebackend? 'html' + %(#{target}(#{attrs[1]})) + elsif parent.document.basebackend? 'docbook' + "\n" \ + "#{target}" \ + "#{attrs[1]}\n" \ + "" + end + end + end + + class LinkStgProcessor < Asciidoctor::Extensions::InlineMacroProcessor + use_dsl + + named :chrome + + def process(parent, target, attrs) + if parent.document.doctype == 'book' \ + or parent.document.doctype == 'article' + "stg #{target}" + elsif parent.document.basebackend? 'html' + %(stg #{target}) + elsif parent.document.basebackend? 'docbook' + "\n" \ + "stg-#{target}" \ + "1\n" \ + "" + end + end + end + + class LinkStgSubProcessor < Asciidoctor::Extensions::InlineMacroProcessor + use_dsl + + named :chrome + + def process(parent, target, attrs) + if parent.document.doctype == 'book' \ + or parent.document.doctype == 'article' + "#{target}" + elsif parent.document.basebackend? 'html' + %(#{target}) + elsif parent.document.basebackend? 'docbook' + "\n" \ + "stg-#{target}" \ + "1\n" \ + "" + end + end + end + + class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor + def process document, output + if document.basebackend? 'docbook' + mansource = document.attributes['mansource'] + manversion = document.attributes['manversion'] + manmanual = document.attributes['manmanual'] + new_tags = "" \ + "#{mansource}\n" \ + "#{manversion}\n" \ + "#{manmanual}\n" + output = output.sub(/<\/refmeta>/, new_tags + "") + end + output + end + end + end +end + +Asciidoctor::Extensions.register do + inline_macro StGit::Documentation::LinkGitProcessor, :linkgit + inline_macro StGit::Documentation::LinkManProcessor, :linkman + inline_macro StGit::Documentation::LinkStgProcessor, :linkstg + inline_macro StGit::Documentation::LinkStgSubProcessor, :linkstgsub + postprocessor StGit::Documentation::DocumentPostProcessor +end diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl new file mode 100755 index 00000000..22c66a8b --- /dev/null +++ b/Documentation/cat-texi.perl @@ -0,0 +1,46 @@ +#!/usr/bin/perl -w + +use strict; +use warnings; + +my @menu = (); +my $output = $ARGV[0]; + +open my $tmp, '>', "$output.tmp"; + +while () { + next if (/^\\input texinfo/../\@node Top/); + next if (/^\@bye/ || /^\.ft/); + if (s/^\@top (.*)/\@node $1,,,Top/) { + push @menu, $1; + } + s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//; + s/\@anchor\{[^{}]*\}//g; + print $tmp $_; +} +close $tmp; + +print '\input texinfo +@setfilename stgitman.info +@documentencoding UTF-8 +@dircategory Development +@direntry +* StGit Man Pages: (stgitman). Manual pages for StGit +@end direntry +@node Top,,, (dir) +@top StGit Manual Pages +@documentlanguage en +@menu +'; + +for (@menu) { + print "* ${_}::\n"; +} +print "\@end menu\n"; +open $tmp, '<', "$output.tmp"; +while (<$tmp>) { + print; +} +close $tmp; +print "\@bye\n"; +unlink "$output.tmp"; diff --git a/Documentation/docbook-xsl.css b/Documentation/docbook-xsl.css new file mode 100644 index 00000000..e11c8f05 --- /dev/null +++ b/Documentation/docbook-xsl.css @@ -0,0 +1,296 @@ +/* + CSS stylesheet for XHTML produced by DocBook XSL stylesheets. + Tested with XSL stylesheets 1.61.2, 1.67.2 +*/ + +span.strong { + font-weight: bold; +} + +body blockquote { + margin-top: .75em; + line-height: 1.5; + margin-bottom: .75em; +} + +html body { + margin: 1em 5% 1em 5%; + line-height: 1.2; + font-family: sans-serif; +} + +body div { + margin: 0; +} + +h1, h2, h3, h4, h5, h6, +div.toc p b, +div.list-of-figures p b, +div.list-of-tables p b, +div.abstract p.title +{ + color: #527bbd; + font-family: tahoma, verdana, sans-serif; +} + +div.toc p:first-child, +div.list-of-figures p:first-child, +div.list-of-tables p:first-child, +div.example p.title +{ + margin-bottom: 0.2em; +} + +body h1 { + margin: .0em 0 0 -4%; + line-height: 1.3; + border-bottom: 2px solid silver; +} + +body h2 { + margin: 0.5em 0 0 -4%; + line-height: 1.3; + border-bottom: 2px solid silver; +} + +body h3 { + margin: .8em 0 0 -3%; + line-height: 1.3; +} + +body h4 { + margin: .8em 0 0 -3%; + line-height: 1.3; +} + +body h5 { + margin: .8em 0 0 -2%; + line-height: 1.3; +} + +body h6 { + margin: .8em 0 0 -1%; + line-height: 1.3; +} + +body hr { + border: none; /* Broken on IE6 */ +} +div.footnotes hr { + border: 1px solid silver; +} + +div.navheader th, div.navheader td, div.navfooter td { + font-family: sans-serif; + font-size: 0.9em; + font-weight: bold; + color: #527bbd; +} +div.navheader img, div.navfooter img { + border-style: none; +} +div.navheader a, div.navfooter a { + font-weight: normal; +} +div.navfooter hr { + border: 1px solid silver; +} + +body td { + line-height: 1.2 +} + +body th { + line-height: 1.2; +} + +ol { + line-height: 1.2; +} + +ul, body dir, body menu { + line-height: 1.2; +} + +html { + margin: 0; + padding: 0; +} + +body h1, body h2, body h3, body h4, body h5, body h6 { + margin-left: 0 +} + +body pre { + margin: 0.5em 10% 0.5em 1em; + line-height: 1.0; + color: navy; +} + +tt.literal, code.literal { + color: navy; + font-family: sans-serif; +} + +code.literal:before { content: "'"; } +code.literal:after { content: "'"; } + +em { + font-style: italic; + color: #064; +} + +div.literallayout p { + padding: 0em; + margin: 0em; +} + +div.literallayout { + font-family: monospace; + margin: 0em; + color: navy; + border: 1px solid silver; + background: #f4f4f4; + padding: 0.5em; +} + +.programlisting, .screen { + border: 1px solid silver; + background: #f4f4f4; + margin: 0.5em 10% 0.5em 0; + padding: 0.5em 1em; +} + +div.sidebar { + background: #ffffee; + margin: 1.0em 10% 0.5em 0; + padding: 0.5em 1em; + border: 1px solid silver; +} +div.sidebar * { padding: 0; } +div.sidebar div { margin: 0; } +div.sidebar p.title { + font-family: sans-serif; + margin-top: 0.5em; + margin-bottom: 0.2em; +} + +div.bibliomixed { + margin: 0.5em 5% 0.5em 1em; +} + +div.glossary dt { + font-weight: bold; +} +div.glossary dd p { + margin-top: 0.2em; +} + +dl { + margin: .8em 0; + line-height: 1.2; +} + +dt { + margin-top: 0.5em; +} + +dt span.term { + font-style: normal; + color: navy; +} + +div.variablelist dd p { + margin-top: 0; +} + +div.itemizedlist li, div.orderedlist li { + margin-left: -0.8em; + margin-top: 0.5em; +} + +ul, ol { + list-style-position: outside; +} + +div.sidebar ul, div.sidebar ol { + margin-left: 2.8em; +} + +div.itemizedlist p.title, +div.orderedlist p.title, +div.variablelist p.title +{ + margin-bottom: -0.8em; +} + +div.revhistory table { + border-collapse: collapse; + border: none; +} +div.revhistory th { + border: none; + color: #527bbd; + font-family: tahoma, verdana, sans-serif; +} +div.revhistory td { + border: 1px solid silver; +} + +/* Keep TOC and index lines close together. */ +div.toc dl, div.toc dt, +div.list-of-figures dl, div.list-of-figures dt, +div.list-of-tables dl, div.list-of-tables dt, +div.indexdiv dl, div.indexdiv dt +{ + line-height: normal; + margin-top: 0; + margin-bottom: 0; +} + +/* + Table styling does not work because of overriding attributes in + generated HTML. +*/ +div.table table, +div.informaltable table +{ + margin-left: 0; + margin-right: 5%; + margin-bottom: 0.8em; +} +div.informaltable table +{ + margin-top: 0.4em +} +div.table thead, +div.table tfoot, +div.table tbody, +div.informaltable thead, +div.informaltable tfoot, +div.informaltable tbody +{ + /* No effect in IE6. */ + border-top: 2px solid #527bbd; + border-bottom: 2px solid #527bbd; +} +div.table thead, div.table tfoot, +div.informaltable thead, div.informaltable tfoot +{ + font-weight: bold; +} + +div.mediaobject img { + border: 1px solid silver; + margin-bottom: 0.8em; +} +div.figure p.title, +div.table p.title +{ + margin-top: 1em; + margin-bottom: 0.4em; +} + +@media print { + div.navheader, div.navfooter { display: none; } +} diff --git a/Documentation/docbook.xsl b/Documentation/docbook.xsl new file mode 100644 index 00000000..da8b05b9 --- /dev/null +++ b/Documentation/docbook.xsl @@ -0,0 +1,8 @@ + + + + diff --git a/Documentation/fix-texi.perl b/Documentation/fix-texi.perl new file mode 100755 index 00000000..ff7d78f6 --- /dev/null +++ b/Documentation/fix-texi.perl @@ -0,0 +1,15 @@ +#!/usr/bin/perl -w + +while (<>) { + if (/^\@setfilename/) { + $_ = "\@setfilename git.info\n"; + } elsif (/^\@direntry/) { + print '@dircategory Development +@direntry +* Git: (git). A fast distributed revision control system +@end direntry +'; } + unless (/^\@direntry/../^\@end direntry/) { + print; + } +} diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl new file mode 100644 index 00000000..b4d315cb --- /dev/null +++ b/Documentation/manpage-1.72.xsl @@ -0,0 +1,14 @@ + + + + + + +▓ +⌂ + + diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in new file mode 100644 index 00000000..e800904d --- /dev/null +++ b/Documentation/manpage-base-url.xsl.in @@ -0,0 +1,10 @@ + + + + +@@MAN_BASE_URL@@ + + diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl new file mode 100644 index 00000000..a264fa61 --- /dev/null +++ b/Documentation/manpage-base.xsl @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + sp + + + + + + + + br + + + diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl new file mode 100644 index 00000000..94d6c1b5 --- /dev/null +++ b/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,18 @@ + + + + + + + fB + + + fR + + + diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 00000000..a48f5b11 --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,13 @@ + + + + + + +\ +. + + diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl new file mode 100644 index 00000000..aeb8839f --- /dev/null +++ b/Documentation/manpage-quote-apos.xsl @@ -0,0 +1,16 @@ + + + + + + + + ' + \(aq + + + + diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl new file mode 100644 index 00000000..a63c7632 --- /dev/null +++ b/Documentation/manpage-suppress-sp.xsl @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + diff --git a/Documentation/manpage.xsl b/Documentation/manpage.xsl new file mode 100644 index 00000000..ef64bab1 --- /dev/null +++ b/Documentation/manpage.xsl @@ -0,0 +1,3 @@ + + + diff --git a/Documentation/stg.txt b/Documentation/stg.txt index eefd6b8d..6684496e 100644 --- a/Documentation/stg.txt +++ b/Documentation/stg.txt @@ -144,7 +144,7 @@ include::command-list.txt[] CONFIGURATION MECHANISM ----------------------- -StGit uses the same configuration mechanism as Git. See linkman:git[7] +StGit uses the same configuration mechanism as Git. See linkgit:git[7] for more details. TEMPLATES diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl new file mode 100644 index 00000000..0f8ff07e --- /dev/null +++ b/Documentation/texi.xsl @@ -0,0 +1,26 @@ + + + + + + + refsect + + + + + + + + + + + + + diff --git a/Documentation/tutorial.conf b/Documentation/tutorial.conf index 5b8d95f2..0cb287a4 100644 --- a/Documentation/tutorial.conf +++ b/Documentation/tutorial.conf @@ -1,3 +1,21 @@ [titles] underlines="##","==","--","~~","^^" +[linkgit-inlinemacro] +{target}{0?({0})} + +[linkstg-inlinemacro] +stg {target}{0?({0})} + +[linkstgsub-inlinemacro] +{target} + +ifdef::backend-docbook[] +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. +[listingblock] +{title} + +| + +{title#} +endif::backend-docbook[] diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt index 14505d39..c67184e2 100644 --- a/Documentation/tutorial.txt +++ b/Documentation/tutorial.txt @@ -10,7 +10,7 @@ them in various ways. This tutorial assumes you are already familiar with the basics of Git (for example, branches, commits, and conflicts). For more information -on Git, see linkman:git[1] or link:https://git-scm.com/[the Git home +on Git, see linkgit:git[1] or link:https://git-scm.com/[the Git home page]. @@ -110,7 +110,7 @@ this example, I've added the +$$print 'My first patch!'$$+ line to the file +stgit/main.py+, at around line 171.) Since the patch is also a regular Git commit, you can also look at it -with regular Git tools such as linkman:gitk[]. +with regular Git tools such as linkgit:gitk[]. Creating another patch ---------------------- @@ -156,7 +156,7 @@ make. The minus sign says that +credit+ is 'unapplied' -- this means that it's been temporarily put aside. If you look at the +AUTHORS+ file, you'll see that our change to it is gone; and tools such as -linkman:gitk[] will not show it, because it's been edited out of the +linkgit:gitk[] will not show it, because it's been edited out of the Git history. But it's just one linkstg:push[] command away from being restored: @@ -1035,7 +1035,7 @@ that had the conflict. To investigate the reason of conflicts, you can use the +d b+, +d o+, and +d t+ commands to, respectively, show the diffs against the merge base, our branch, or their branch. +d c+ shows a combined diff. See -linkman:git-diff[1] for more information about these commands. +linkgit:git-diff[1] for more information about these commands. A more powerful tool to resolve conflicts is the Emacs +smerge-mode+. To start using it to resolve a conflict, press +d m+. It is outside diff --git a/MANIFEST.in b/MANIFEST.in index 3c6cfeb2..f7f58db6 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,10 +1,13 @@ include AUTHORS include COPYING include Documentation/*.conf +include Documentation/*.css +include Documentation/*.perl +include Documentation/*.rb +include Documentation/*.xsl +include Documentation/*.xsl.in include Documentation/Makefile include Documentation/SubmittingPatches -include Documentation/build-docdep.perl -include Documentation/callouts.xsl include Documentation/stg.txt include Documentation/tutorial.txt include INSTALL diff --git a/build.py b/build.py index f4dabb37..945b910e 100755 --- a/build.py +++ b/build.py @@ -11,10 +11,14 @@ from stgit.completion.bash import write_bash_completion from stgit.completion.fish import write_fish_completion import stgit.main +import stgit.version def main(): op = optparse.OptionParser() + op.add_option( + '--stgit-version', action='store_true', help='Print StGit version', + ) op.add_option( '--asciidoc', metavar='CMD', help='Print asciidoc documentation for a command', ) @@ -34,7 +38,9 @@ def main(): options, args = op.parse_args() if args: op.error('Wrong number of arguments') - if options.asciidoc: + if options.stgit_version: + print(stgit.version.get_version()) + elif options.asciidoc: argparse.write_asciidoc(stgit.main.commands[options.asciidoc], sys.stdout) elif options.commands: for cmd, _, _, _ in commands.get_commands(allow_cached=False):