Re: [PATCH] add documentation to mw-to-git

[Matthieu Moy]

Hi, and thanks for your contribution.

Alexandru Zbarcea  writes:

> Signed-off-by: Alexandru Zbarcea 
> ---
>  contrib/mw-to-git/Makefile |  44 -
>  contrib/mw-to-git/git-mediawiki.txt| 100 
> +
>  contrib/mw-to-git/git-remote-mediawiki.txt |   7 --
>  3 files changed, 142 insertions(+), 9 deletions(-)

Git-Mediawiki did not contain any in-tree documentation, but already has a
user manual:

  https://github.com/moy/Git-Mediawiki/wiki/User-manual

I have no objection to moving the documentation in-tree (I even created
an issue a long time ago but never did it:
https://github.com/moy/Git-Mediawiki/issues/9 ). However, you patch
alone does not do that: it partly duplicates the existing user-manual,
and complements it with (useful) things that did not appear there (doc
for "git mw" and a recap of config variables). I think this is a step in
the wrong direction and I'd very much prefer a single documentation.

Two more things to know about Git-Mediawiki:

https://github.com/moy/Git-Mediawiki/issues/34
Move Git-Mediawiki's code out of git.git's contrib/

Essentially, having the code in git.git's contrib does not bring much
today, and reduces the number of potential contributors. There seems to
be a consensus to move it out of git.git and develop it separately.

One consequence is that asciidoc may not be the best choice as a markup
format. Having a format that renders directly on GitHub probably
overweights the benefit of using the same system as Git. GitHub can
render asciidoc, but needs *.asciidoc file names and won't read the
config file AFAIK.

https://github.com/moy/Git-Mediawiki/issues/33
Git-Mediawiki is looking for a new maintainer

Git-Mediawiki was a fun experience, but I'm not using it as much as I
planed, and my time budget for it approaches 0, so a new maintainer
would be very much welcome (typically to fix issue #34 above).

> +COMMANDS
> +
> +help::
> +Display help information about git mw.
> +
> +preview::
> +Parse and render local file into HTML. Preview a page without actually 
> pushing it to the wiki.

Better write the commands completely like

git mw help::

to avoid ambiguity with git-remote-mediawiki (which is a separate
command).

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] add documentation to mw-to-git

[Alexandru Zbarcea]

Signed-off-by: Alexandru Zbarcea 
---
 contrib/mw-to-git/Makefile |  44 -
 contrib/mw-to-git/git-mediawiki.txt| 100 +
 contrib/mw-to-git/git-remote-mediawiki.txt |   7 --
 3 files changed, 142 insertions(+), 9 deletions(-)

diff --git a/contrib/mw-to-git/Makefile b/contrib/mw-to-git/Makefile
index a4b6f7a..a2b5ed8 100644
--- a/contrib/mw-to-git/Makefile
+++ b/contrib/mw-to-git/Makefile
@@ -12,13 +12,25 @@
 #
 #   make install

+prefix ?= /usr/local
+mandir ?= $(prefix)/share/man
+man1dir ?= $(mandir)/man1
+htmldir ?= $(prefix)/share/doc/git-doc
+
 GIT_MEDIAWIKI_PM=Git/Mediawiki.pm
 SCRIPT_PERL=git-remote-mediawiki.perl
 SCRIPT_PERL+=git-mw.perl
 GIT_ROOT_DIR=../..
 HERE=contrib/mw-to-git/

-INSTALL = install
+INSTALL  ?= install
+RM   ?= rm -f
+
+ASCIIDOC = asciidoc
+XMLTO= xmlto
+
+ASCIIDOC_CONF = ../../Documentation/asciidoc.conf
+MANPAGE_XSL   = ../../Documentation/manpage-normal.xsl

 SCRIPT_PERL_FULL=$(patsubst %,$(HERE)/%,$(SCRIPT_PERL))
 INSTLIBDIR=$(shell $(MAKE) -C $(GIT_ROOT_DIR)/perl \
@@ -26,8 +38,36 @@ INSTLIBDIR=$(shell $(MAKE) -C $(GIT_ROOT_DIR)/perl \
 DESTDIR_SQ = $(subst ','\'',$(DESTDIR))
 INSTLIBDIR_SQ = $(subst ','\'',$(INSTLIBDIR))

+GIT_MEDIAWIKI_DOC := git-mediawiki.1
+GIT_MEDIAWIKI_XML := git-mediawiki.xml
+GIT_MEDIAWIKI_TXT := git-mediawiki.txt
+GIT_MEDIAWIKI_HTML := git-mediawiki.html
+
 all: build

+doc: $(GIT_MEDIAWIKI_DOC) $(GIT_MEDIAWIKI_HTML)
+
+install-doc: install-man install-html
+
+install-man: $(GIT_MEDIAWIKI_DOC)
+ $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+ $(INSTALL) -m 644 $^ $(DESTDIR)$(man1dir)
+
+install-html: $(GIT_MEDIAWIKI_HTML)
+ $(INSTALL) -d -m 755 $(DESTDIR)$(htmldir)
+ $(INSTALL) -m 644 $^ $(DESTDIR)$(htmldir)
+
+$(GIT_MEDIAWIKI_DOC): $(GIT_MEDIAWIKI_XML)
+ $(XMLTO) -m $(MANPAGE_XSL) man $^
+
+$(GIT_MEDIAWIKI_XML): $(GIT_MEDIAWIKI_TXT)
+ $(ASCIIDOC) -b docbook -d manpage -f $(ASCIIDOC_CONF) \
+ -agit_version=$(GIT_VERSION) $^
+
+$(GIT_MEDIAWIKI_HTML): $(GIT_MEDIAWIKI_TXT)
+ $(ASCIIDOC) -b xhtml11 -d manpage -f $(ASCIIDOC_CONF) \
+ -agit_version=$(GIT_VERSION) $^
+
 test: all
  $(MAKE) -C t

@@ -54,4 +94,4 @@ perlcritic:
  perlcritic -5 $(SCRIPT_PERL)
  -perlcritic -2 $(SCRIPT_PERL)

-.PHONY: all test check install_pm install clean perlcritic
+.PHONY: all doc test check install_pm install install-doc install-man
install-html clean perlcritic
diff --git a/contrib/mw-to-git/git-mediawiki.txt
b/contrib/mw-to-git/git-mediawiki.txt
new file mode 100644
index 000..421fbae
--- /dev/null
+++ b/contrib/mw-to-git/git-mediawiki.txt
@@ -0,0 +1,100 @@
+git-mediawiki(1)
+==
+
+NAME
+
+git-mediawiki - Abstracts a Mediawiki as a git repository.
+
+
+SYNOPSIS
+
+[verse]
+'git clone' -c = mediawiki::
+'git fetch' -c =
+'git mw' help
+'git mw' preview
+
+DESCRIPTION
+---
+Git-Mediawiki is a project which aims the creation of a gate
+between git and mediawiki, allowing git users to push and pull
+objects from mediawiki just as one would do with a classic git
+repository thanks to 'remote-helpers'.
+
+[TIP]
+For more information, visit the wiki at
+https://github.com/moy/Git-Mediawiki/wiki
+
+[TIP]
+Limit the pages to be imported. If you don't want to clone the
+whole wiki, you can import only some pages with:
+
+ $ git clone -c remote.origin.pages='A_page Another_page' \
+mediawiki::http://yourwikiadress.com
+
+and/or select the content of MediaWiki Categories with:
+
+$ git clone -c remote.origin.categories='First Second' \
+mediawiki::http://yourwikiadress.com
+
+
+COMMANDS
+
+help::
+Display help information about git mw.
+
+preview::
+Parse and render local file into HTML. Preview a page without
actually pushing it to the wiki.
+
+OPTIONS FOR git
+-
+
+remote..pages::
+Imports only the page specified.
+
+remote..categories::
+Imports only the category page specified.
+
+remote..shallow::
+Imports only the last revision of a wiki
+
+remote..mwLogin::
+Login username for the wiki
+
+remote..mwDomain::
+If your wiki requires specifying a domain when logging in (if you
use LDAP authentication for instance), this value represents the
domain for your 'remote..mwLogin'.
+
+remote..mwPassword::
+Login password for the wiki
+
+remote..dumbPush::
+If 'true', then 'git push' will not touch the MediaWiki metadata,
and will ask you to reimport history after a successful push,
typically with 'git pull --rebase'. For those who know 'git svn', in
this mode, 'git push; git pull --rebase' is the equivalent of 'git svn
dcommit'.
+
+remote..fetchStrategy::
+by_page::
+This is the most efficient method when cloning a small subset
of a very active wiki. On the other hand, fetching from a wiki with
little activity but many pages is long (the tool has to query every
page even to say "Everything up to date").
+
+by_rev::
+Then, git-remote-mediawiki will query the whole