NotificationsYou must be signed in to change notification settings
Fork5
Star26

Commit6639785

Michael Paquier

committed

Use asciidoc and xmlto to automatic generation of man and html docs

This has the merit to put all the documentation of the project into asingle banner, and to centralize all the project in a single place atcode level.Compiling documentation can be made by setting the variables ASCIIDOCand XMLTO. As PostgreSQL extension system is not that smart for docgeneration, some custom Makefile path is used to install man pages intoa folder that could directly by used in MANPATH.

1 parent1c3512f commit6639785Copy full SHA for 6639785

File tree

5 files changed

+281

-200

lines changed

5 files changed

+281

-200

lines changed

`‎Makefile`

Lines changed: 33 additions & 3 deletions

Original file line number	Diff line number	Diff line change
`@@ -18,11 +18,19 @@ SRCS = \`
`18`	`18`	`pgut/pgut.c\`
`19`	`19`	`pgut/pgut-port.c`
`20`	`20`	`OBJS =$(SRCS:.c=.o)`
`21`		`-# pg_crc.c and are copied from PostgreSQL source tree.`
`22`	`21`
`23`		`-DOCS = pg_rman.txt`
	`22`	`+DOCS = doc/pg_rman.txt`
	`23`	`+`
	`24`	`+# asciidoc and xmlto are present, so install the html documentation and man`
	`25`	`+# pages as well. html is part of the vanilla documentation. Man pages need a`
	`26`	`+# special handling at installation.`
	`27`	`+ifneq ($(ASCIIDOC),)`
	`28`	`+ifneq ($(XMLTO),)`
	`29`	`+man_DOCS = doc/pg_rman.1`
	`30`	`+DOCS += doc/pg_rman.html doc/README.html`
	`31`	`+endif# XMLTO`
	`32`	`+endif# ASCIIDOC`
`24`	`33`
`25`		`-# XXX for debug, add -g and disable optimization`
`26`	`34`	`PG_CPPFLAGS = -I$(libpq_srcdir)`
`27`	`35`	`PG_LIBS =$(libpq_pgport)`
`28`	`36`
`@@ -44,3 +52,25 @@ LIBS := $(filter-out -lxml2, $(LIBS))`
`44`	`52`	`LIBS :=$(filter-out -lxslt,$(LIBS))`
`45`	`53`
`46`	`54`	`$(OBJS): pg_rman.h`
	`55`	`+`
	`56`	`+# Part related to documentation`
	`57`	`+# Compile documentation as well is ASCIIDOC and XMLTO are defined`
	`58`	`+ifneq ($(ASCIIDOC),)`
	`59`	`+ifneq ($(XMLTO),)`
	`60`	`+all: docs`
	`61`	`+docs:`
	`62`	`+$(MAKE) -C doc/`
	`63`	`+`
	`64`	`+# Special handling for man pages, they need to be in a dedicated folder`
	`65`	`+install: install-man`
	`66`	`+`
	`67`	`+install-man:`
	`68`	`+$(MKDIR_P)'$(DESTDIR)$(docdir)/$(docmoduledir)/man1/'`
	`69`	`+$(INSTALL_DATA)$(man_DOCS)'$(DESTDIR)$(docdir)/$(docmoduledir)/man1/'`
	`70`	`+endif# XMLTO`
	`71`	`+endif# ASCIIDOC`
	`72`	`+`
	`73`	`+# Clean up documentation as well`
	`74`	`+clean: clean-docs`
	`75`	`+clean-docs:`
	`76`	`+$(MAKE) -C doc/ clean`

`‎README`

Lines changed: 18 additions & 4 deletions

Original file line number	Diff line number	Diff line change
`@@ -23,13 +23,16 @@ Compiling pg_rman requires a PostgreSQL installation and can be done in`
`23`	`23`	`two ways:`
`24`	`24`
`25`	`25`	`1. Put pg_rman project directory inside PostgreSQL source tree as`
`26`		`-contrib/pg_rman, and use"make" to compile`
	`26`	`+contrib/pg_rman, and usethis command for compilation:`
`27`	`27`
`28`		`-or`
	`28`	`+$ cd $POSTGRES_SOURCE/contrib/pg_rman`
	`29`	`+$ make`
`29`	`30`
`30`	`31`	`2. Keep the project directory as-is and use the PGXS development`
`31`	`32`	`infrastructure provided by a PostgreSQL installation to perform the`
`32`		`-compilation: "make USE_PGXS=1"`
	`33`	`+compilation:`
	`34`	`+`
	`35`	`+$ make USE_PGXS=1`
`33`	`36`
`34`	`37`	`In addition, you must have pg_config in $PATH.`
`35`	`38`
`@@ -44,7 +47,18 @@ pg_rman has been tested on Linux and Unix-based platforms.`
`44`	`47`	`Documentation`
`45`	`48`	`-------------`
`46`	`49`
`47`		`-All the documentation is written and maintained in pg_rman.txt.`
	`50`	`+All the documentation is maintained in doc/ as text file, that is then`
	`51`	`+fetched by asciidoc to generate automatically man pages and html`
	`52`	`+documentation.`
	`53`	`+`
	`54`	`+In order to generate the documentation, the variables XMLTO and ASCIIDOC`
	`55`	`+need to be set to proper values indicating where are located the binaries`
	`56`	`+of respectively xmlto and asciidoc. An example of build is as follows:`
	`57`	`+`
	`58`	`+$ make USE_PGXS=1 ASCIIDOC=asciidoc XMLTO=xmlto`
	`59`	`+`
	`60`	`+They could as well be set as environment variables for development`
	`61`	`+purposes.`
`48`	`62`
`49`	`63`	`Regression tests`
`50`	`64`	`----------------`

`‎doc/.gitignore`

Lines changed: 4 additions & 0 deletions

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,4 @@`
	`1`	`+# Documentation entries`
	`2`	`+/*.html`
	`3`	`+/*.xml`
	`4`	`+/pg_rman.1`

`‎doc/Makefile`

Lines changed: 33 additions & 0 deletions

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,33 @@`
	`1`	`+`
	`2`	`+manpages = pg_rman.1`
	`3`	`+`
	`4`	`+EXTRA_DIST = pg_rman.txt Makefile$(manpages)`
	`5`	`+`
	`6`	`+htmls = pg_rman.html README.html`
	`7`	`+`
	`8`	`+# We have asciidoc and xmlto, so build everything and define correct`
	`9`	`+# rules for build.`
	`10`	`+ifneq ($(ASCIIDOC),)`
	`11`	`+ifneq ($(XMLTO),)`
	`12`	`+dist_man_MANS =$(manpages)`
	`13`	`+doc_DATA =$(htmls)`
	`14`	`+`
	`15`	`+pg_rman.1: pg_rman.xml$(doc_DATA)`
	`16`	`+$(XMLTO) man$<`
	`17`	`+`
	`18`	`+%.xml:%.txt`
	`19`	`+$(ASCIIDOC) -b docbook -d manpage -o$@$<`
	`20`	`+`
	`21`	`+%.html:%.txt`
	`22`	`+$(ASCIIDOC) -a toc -o$@$<`
	`23`	`+`
	`24`	`+README.html: ../README`
	`25`	`+$(ASCIIDOC) -a toc -o$@$<`
	`26`	`+`
	`27`	`+endif# XMLTO`
	`28`	`+endif# ASCIIDOC`
	`29`	`+`
	`30`	`+clean:`
	`31`	`+rm -rf$(manpages).html.xml`
	`32`	`+`
	`33`	`+.PHONY: clean`

0 commit comments

Comments

(0)

Movatterモバイル変換

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Commit6639785

File tree

5 files changed

5 files changed

`‎Makefile`

`‎README`

`‎doc/.gitignore`

`‎doc/Makefile`

0 commit comments