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

From: Matthieu Moy <[email-masked]>
Date: Tue, 05 Jul 2016 15:09:44 +0200

Hi, and thanks for your contribution.

Alexandru Zbarcea <[email-masked]> writes:

> Signed-off-by: Alexandru Zbarcea <[email-masked]>
> ---
>  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/