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

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Jul 5, 2016, 13:09 UTC
Message-ID: <vpq7fd0jko7.fsf@anie.imag.fr>
In-Reply-To: <CAGycqjyzXg-FNrp8n9QFE8-uF=OecMyXgHerk_RERiMkpdoz9A@mail.gmail.com>

Hi, and thanks for your contribution.

Alexandru Zbarcea <alexz@apache.org> writes:

Show 6 quoted lines

> Signed-off-by: Alexandru Zbarcea <alexz@apache.org>
> ---
>  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).

Show 7 quoted lines

> +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/