[gentoo-catalyst] [PATCH] Makefile: Use asciidoc and Pandoc to generate MediaWiki doc versions

[gentoo-catalyst] [PATCH] Makefile: Use asciidoc and Pandoc to generate MediaWiki doc versions

[wking]

We need this because hosting content under:

  https://www.gentoo.org/proj/

is deprecated, with per-project documentation migrating to the wiki [1]

* `--attribute 'toc!'` disables AsciiDoc's table of contents [2],
  which Pandoc doesn't like.
* The Pandoc invocation is about as basic as it gets [3].

[1]: https://wiki.gentoo.org/wiki/Gentoo_Wiki:Developer_Central/Project_pages#Migration_from_www.gentoo.org.2Fproj.2F
[2]: http://asciidoc.org/userguide.html#X91
[3]: http://johnmacfarlane.net/pandoc/README.html#using-pandoc
---
[1] also mentions that the per-project pages are already hosted in
converted form.  For example:

  http://dev.gentoo.org/~swift/tmp/proj2wiki/releng/catalyst/

if folks want to copy-paste into the wiki.  I don't think I have
permission (as a non releng/Catalyst member) to create or edit stuff
in the Project:releng namespace on the wiki, but I suggest folks
dropping the MediaWiki version of the HOWTO in should reference the
source Git commit in their MediaWiki commit:

  auto-generated from ee08256 (doc/HOWTO.txt: Fix stage descriptions,
  and add extra context, 2013-12-19).

Cheers,
Trevor

 Makefile | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Makefile b/Makefile
index 98accbe..0c23cf1 100644
--- a/Makefile
+++ b/Makefile
@@ -8,6 +8,7 @@ MAN_PAGE_INCLUDES = doc/subarches.generated.txt doc/targets.generated.txt
 DOC_SOURCES = $(filter-out $(MAN_PAGE_SOURCES) $(MAN_PAGE_INCLUDES),$(wildcard doc/*.txt))
 DOCS = $(patsubst doc/%.txt,files/%.html,$(DOC_SOURCES))
 DOC_SIDE_EFFECTS  = files/docbook-xsl.css
+MEDIAWIKI_DOCS = $(patsubst files/%.html, wiki/%.mw, $(DOCS))
 EXTRA_DIST = $(MAN_PAGES) $(DOCS) $(DOC_SIDE_EFFECTS)
 GENERATED_FILES = $(MAN_PAGES) $(MAN_PAGE_INCLUDES) $(DOCS) $(DOC_SIDE_EFFECTS)
 
@@ -16,6 +17,8 @@ distdir = catalyst-$(PACKAGE_VERSION)
 
 all: $(EXTRA_DIST)
 
+mediawiki: $(MEDIAWIKI_DOCS)
+
 $(MAN_PAGES): files/%: doc/%.txt doc/asciidoc.conf Makefile catalyst
 	a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=$(PACKAGE_VERSION)" \
 		 --format=manpage -D files "$<"
@@ -34,6 +37,16 @@ $(DOCS): files/%.html: doc/%.txt doc/asciidoc.conf Makefile
 	a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=$(PACKAGE_VERSION)" \
 		 --format=xhtml -D files "$<"
 
+wiki/%.html: doc/%.txt doc/asciidoc.conf Makefile | wiki
+	a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=$(PACKAGE_VERSION)" \
+		 --format=xhtml --attribute 'toc!' -D wiki "$<"
+
+wiki/%.mw: wiki/%.html
+	pandoc -f html -t mediawiki -o "$@" "$<"
+
+wiki:
+	mkdir -p wiki
+
 $(DOC_SIDE_EFFECTS): $(firstword $(DOCS))
 
 clean:
-- 
1.8.4

[gentoo-catalyst] Re: [PATCH] Makefile: Use asciidoc and Pandoc to generate MediaWiki doc versions

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 842 bytes --]

On Wed, Jan 29, 2014 at 04:56:57PM -0800, wking@nott wrote:
> +wiki/%.mw: wiki/%.html
> +	pandoc -f html -t mediawiki -o "$@" "$<"

To avoid accidental changes using the wiki interface, maybe we should
have:

  wiki/%.mw: wiki/header wiki/%.mw-raw
  	cat $^ > "$@"

  wiki/%.mw: wiki/%.html
  	pandoc -f html -t mediawiki -o "$@" "$<"

with a new wiki/header file containing something like:

  This file is autogenerated from
  http://git.overlays.gentoo.org/gitweb/?p=proj/catalyst.git.
  Please send changes to gentoo-catalyst@ instead of editing this file
  directly.

Thoughs?

This series probably needs a 'wiki' entry in .gitignore too.

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]