[pacman-contrib] [PATCH 1/3] Initial setup for docs
Signed-off-by: Johannes Löthberg <johannes@kyriasis.com> --- Makefile.am | 5 +++- configure.ac | 27 ++++++++++++++++-- doc/asciidoc-override.css | 7 +++++ doc/asciidoc.conf | 72 +++++++++++++++++++++++++++++++++++++++++++++++ doc/footer.txt | 21 ++++++++++++++ 5 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 doc/asciidoc-override.css create mode 100644 doc/asciidoc.conf create mode 100644 doc/footer.txt diff --git a/Makefile.am b/Makefile.am index 43b934a..ca86231 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,5 +1,8 @@ SUBDIRS = src lib +if WANT_DOC +SUBDIRS += doc +endif DIST_SUBDIRS = $(SUBDIRS) -DISTCHECK_CONFIGURE_FLAGS = --disable-git-version +DISTCHECK_CONFIGURE_FLAGS = --enable-doc --disable-git-version diff --git a/configure.ac b/configure.ac index 0c973f6..fb6f9c3 100644 --- a/configure.ac +++ b/configure.ac @@ -17,6 +17,11 @@ AC_ARG_WITH(vim-dir, [AS_HELP_STRING([--with-vim-dir=PATH], [set the location of the vim runtime file directory])], [vim_dir=$withval], [vim_dir=$pkgdatadir/vim]) +# Help line for documentation +AC_ARG_ENABLE(doc, + AS_HELP_STRING([--disable-doc], [prevent make from looking at doc/ dir]), + [wantdoc=$enableval], [wantdoc=yes]) + # Help line for debug AC_ARG_ENABLE(debug, AS_HELP_STRING([--enable-debug], [enable debugging support]), @@ -87,6 +92,23 @@ AC_DEFINE_UNQUOTED([vim_dir], "$vim_dir", [The location of the vim runtime file SIZECMD="stat -c %s" AC_SUBST(SIZECMD) +# Check for documentation support and status +AC_CHECK_PROGS([ASCIIDOC], [asciidoc]) +AC_MSG_CHECKING([for building documentation]) +if test "x$wantdoc" = "xyes" ; then + if test $ASCIIDOC ; then + AC_MSG_RESULT([yes, enabled by configure]) + else + asciidoc="(warning : asciidoc not installed)" + AC_MSG_RESULT([yes $asciidoc]) + fi + wantdoc=yes +else + AC_MSG_RESULT([no, disabled by configure]) + wantdoc=no +fi +AM_CONDITIONAL(WANT_DOC, test "x$wantdoc" = "xyes") + # Enable or disable debug code if test "x$debug" = "xyes" ; then AC_MSG_RESULT(yes) @@ -135,9 +157,10 @@ else fi AC_CONFIG_FILES([ - Makefile - src/Makefile lib/Makefile + src/Makefile + doc/Makefile + Makefile ]) AC_OUTPUT diff --git a/doc/asciidoc-override.css b/doc/asciidoc-override.css new file mode 100644 index 0000000..328c8fc --- /dev/null +++ b/doc/asciidoc-override.css @@ -0,0 +1,7 @@ +table th, table td { + padding: 0.2em 1em; +} + +table td p.table { + margin: 0; +} diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf new file mode 100644 index 0000000..68ab5b8 --- /dev/null +++ b/doc/asciidoc.conf @@ -0,0 +1,72 @@ +## linkman: macro +# Inspired by/borrowed from the GIT source tree at Documentation/asciidoc.conf +# +# Usage: linkman:command[manpage-section] +# +# Note, {0} is the manpage section, while {target} is the command. +# +# Show man link as: <command>(<section>); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?P<name>linkman):(?P<target>\S*?)\[(?P<attrlist>.*?)\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +backslash=\ +tilde=~ +apostrophe=' +backtick=` +litdd=-- + +ifdef::backend-docbook[] +[linkman-inlinemacro] +{0%{target}} +{0#<citerefentry>} +{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>} +{0#</citerefentry>} +endif::backend-docbook[] + +ifdef::backend-docbook[] +ifndef::docbook-xsl-172[] +# "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] +<example><title>{title}</title> +<literallayout> +| +</literallayout> +{title#}</example> +endif::docbook-xsl-172[] +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] +<refentry> +<refentryinfo> +<date>{pacman_contrib_version}</date> +</refentryinfo> +<refmeta> +<refentrytitle>{mantitle}</refentrytitle> +<manvolnum>{manvolnum}</manvolnum> +<refmiscinfo class="source">Pacman-contrib</refmiscinfo> +<refmiscinfo class="version">{pacman_contrib_version}</refmiscinfo> +<refmiscinfo class="manual">Pacman-contrib Manual</refmiscinfo> +</refmeta> +<refnamediv> + <refname>{manname}</refname> + <refpurpose>{manpurpose}</refpurpose> +</refnamediv> +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[linkman-inlinemacro] +<a href="{target}.{0}.html">{target}{0?({0})}</a> +endif::backend-xhtml11[] diff --git a/doc/footer.txt b/doc/footer.txt new file mode 100644 index 0000000..1388dfa --- /dev/null +++ b/doc/footer.txt @@ -0,0 +1,21 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// + +Bugs +---- +Bugs? You must be kidding; there are no bugs in this software. But if we +happen to be wrong, send us an email with as much detail as possible to +mailto:pacman-contrib@lists.archlinux.org[]. + + +Authors +------- + +Current maintainers: + +* Johannes Löthberg <johannes@kyriasis.com> +* Daniel M. Capella <polyzen@archlinux.info> + +For additional contributors, use `git shortlog -s` on the pacman-contrib.git +repository. -- 2.10.0
Signed-off-by: Johannes Löthberg <johannes@kyriasis.com> --- doc/Makefile.am | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/pactree.8.txt | 72 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 doc/Makefile.am create mode 100644 doc/pactree.8.txt diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..df97fff --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,93 @@ +# We have to do some funny stuff here with the manpages. In order to ensure +# a dist tarball doesn't get put out there without manpages, we keep those +# files listed in EXTRA_DIST no matter what. However, we only add them to +# man_MANS if --enable-asciidoc and/or --enable-doxygen are used. + +ASCIIDOC_MANS = \ + pactree.8 + +HTML_MANPAGES = \ + pactree.8.html + +HTML_DOCS = \ + $(HTML_MANPAGES) + +EXTRA_DIST = \ + pactree.8.txt \ + footer.txt \ + $(ASCIIDOC_MANS) + +# Files that should be removed, but which Automake does not know. +MOSTLYCLEANFILES = *.xml $(ASCIIDOC_MANS) $(HTML_DOCS) repo-remove.8 website.tar.gz + +# Ensure manpages are fresh when building a dist tarball +dist-hook: + $(MAKE) $(AM_MAKEFLAGS) clean + $(MAKE) $(AM_MAKEFLAGS) all + +if USE_GIT_VERSION +GIT_VERSION := $(shell sh -c 'git describe --abbrev=4 --dirty | sed s/^v//') +REAL_PACKAGE_VERSION = $(GIT_VERSION) +else +REAL_PACKAGE_VERSION = $(PACKAGE_VERSION) +endif + +man_MANS = +dist_man_MANS = $(ASCIIDOC_MANS) + +html: $(HTML_DOCS) + +website: website.tar.gz + +.PHONY: html website + +website.tar.gz: html + $(AM_V_GEN)bsdtar czf $@ $(HTML_DOCS) \ + asciidoc-override.css \ + -C /etc/asciidoc/stylesheets/ \ + asciidoc.css \ + -C /etc/asciidoc/javascripts/ \ + asciidoc.js \ + -C /etc/asciidoc/ \ + images + +pkgdatadir = ${datadir}/${PACKAGE} + +ASCIIDOC_OPTS = \ + -f $(srcdir)/asciidoc.conf \ + -a pacman_contrib_version="$(REAL_PACKAGE_VERSION)" \ + -a pacman_contrib_date="`date +%Y-%m-%d`" \ + -a pkgdatadir=$(pkgdatadir) \ + -a localstatedir=$(localstatedir) \ + -a sysconfdir=$(sysconfdir) + +A2X_OPTS = \ + --no-xmllint \ + -d manpage \ + -f manpage \ + --xsltproc-opts='-param man.endnotes.list.enabled 0 -param man.endnotes.are.numbered 0' + +# These rules are due to the includes and files of the asciidoc text +$(ASCIIDOC_MANS): asciidoc.conf footer.txt Makefile.am + $(AM_V_GEN)a2x $(A2X_OPTS) --asciidoc-opts="$(ASCIIDOC_OPTS) --out-file=./$@.xml" $(srcdir)/$@.txt + +%.html: %.txt + $(AM_V_GEN)asciidoc $(ASCIIDOC_OPTS) -o - $*.txt | \ + sed -e 's/\r$$//' > $@ + +HACKING.html: ../HACKING + $(AM_V_GEN)asciidoc $(ASCIIDOC_OPTS) -o - ../HACKING | \ + sed -e 's/\r$$//' > $@ + +# Customizations for certain HTML docs +$(HTML_MANPAGES): asciidoc.conf footer.txt Makefile.am +$(HTML_OTHER): asciidoc.conf Makefile.am +%.html: ASCIIDOC_OPTS += -a linkcss -a toc -a icons -a max-width=960px -a stylesheet=asciidoc-override.css +%.8.html: ASCIIDOC_OPTS += -d manpage +%.5.html: ASCIIDOC_OPTS += -d manpage +%.3.html: ASCIIDOC_OPTS += -d manpage + +# Dependency rules +pactree.8 pactree.8.html: pactree.8.txt + +# vim:set noet: diff --git a/doc/pactree.8.txt b/doc/pactree.8.txt new file mode 100644 index 0000000..4c391c0 --- /dev/null +++ b/doc/pactree.8.txt @@ -0,0 +1,72 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +pactree(8) +========= + +Name +---- +pactree - package dependency tree viewer + + +Synopsis +-------- +'pactree' [options] package + + +Description +----------- +Pactree produces a dependency tree for a package. + +By default, a tree-like output is generated, but with the '\--graph' option, a Graphviz +description is generated. + + +Options +------- +*-a, \--ascii*:: + Use ASCII characters for tree formatting. By default, pactree will use Unicode + line drawing characters if it is able to detect that the locale supports them. + +*-b, \--dbpath*:: + Specify an alternative database location. + +*-c, \--color*:: + Colorize output. + +*-d, \--depth <num>*:: + Limits the number of levels of dependency to show. A zero means + show the named package only, one shows the packages that are directly + required. + +*-g, \--graph*:: + Generate a Graphviz description. If this option is given, the '\--color' and + '\--linear' options are ignored. + +*-h, \--help*:: + Output syntax and command-line options. + +*-l, \--linear*:: + Prints package names at the start of each line, one per line. + +*-o, \--optdeps*:: + Show packages that are optionally depended upon by the named package. + +*-r, \--reverse*:: + Show packages that depend on the named package. + +*-s, \--sync*:: + Read package data from sync databases instead of local database. + +*-u, \--unique*:: + List dependent packages once. Implies '\--linear'. + +*\--config <file>*:: + Specify an alternate pacman configuration file. + + +See Also +-------- +linkman:pacman[8], linkman:pacman.conf[5], linkman:makepkg[8] + +include::footer.txt[] -- 2.10.0
Signed-off-by: Johannes Löthberg <johannes@kyriasis.com> --- doc/.gitignore | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..071d048 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,3 @@ +*.8 +*.html +website.tar.gz -- 2.10.0
participants (1)
-
Johannes Löthberg