* [PATCH] add documentation to mw-to-git
@ 2016-07-04 22:27 Alexandru Zbarcea
2016-07-05 13:09 ` Matthieu Moy
0 siblings, 1 reply; 2+ messages in thread
From: Alexandru Zbarcea @ 2016-07-04 22:27 UTC (permalink / raw)
To: git
Cc: Benoit Person, Célestin Matte, David Aguilar, Elia Pinto,
Guillaume Sasdy, Jeff King, Jeremie Nikaes, Jonathan Nieder,
Junio C Hamano, Masanari Iida, NGUYEN Kim Thuat, Pavel Volek,
Simon Cathebras, Stefano Lattarini
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(-)
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 0000000..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 <name>=<value> mediawiki::<repository>
+'git fetch' -c <name>=<value>
+'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.<name>.pages::
+ Imports only the page specified.
+
+remote.<name>.categories::
+ Imports only the category page specified.
+
+remote.<name>.shallow::
+ Imports only the last revision of a wiki
+
+remote.<name>.mwLogin::
+ Login username for the wiki
+
+remote.<name>.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.<name>.mwLogin'.
+
+remote.<name>.mwPassword::
+ Login password for the wiki
+
+remote.<name>.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.<name>.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 wiki for new
revisions, and will filter-out revisions that should not be fetched
because they do not touch tracked pages. In this case, for example,
fetching from an up-to-date wiki is done in constant time (not
O(number of pages)).
+
+AUTHOR
+------
+The authors from the git log (alphabetic)::
+ Benoit Person <benoit.person@gmail•com>
+ Célestin Matte <celestin.matte@ensimag•fr>
+ David Aguilar <davvid@gmail•com>
+ Elia Pinto <gitter.spiros@gmail•com>
+ Guillaume Sasdy <guillaume.sasdy@ensimag•imag.fr>
+ Jeff King <peff@peff•net>
+ Jeremie Nikaes <jeremie.nikaes@ensimag•imag.fr>
+ Jonathan Nieder <jrnieder@gmail•com>
+ Junio C Hamano <gitster@pobox•com>
+ Masanari Iida <standby24x7@gmail•com>
+ NGUYEN Kim Thuat <Kim-Thuat.Nguyen@ensimag•imag.fr>
+ Pavel Volek <Pavel.Volek@ensimag•imag.fr>
+ Simon Cathebras <simon.cathebras@ensimag•imag.fr>
+ Stefano Lattarini <stefano.lattarini@gmail•com>
+
+GIT
+---
+Part of the linkgit:git[1] suite
\ No newline at end of file
diff --git a/contrib/mw-to-git/git-remote-mediawiki.txt
b/contrib/mw-to-git/git-remote-mediawiki.txt
deleted file mode 100644
index 23b7ef9..0000000
--- a/contrib/mw-to-git/git-remote-mediawiki.txt
+++ /dev/null
@@ -1,7 +0,0 @@
-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.
-
-For more information, visit the wiki at
-https://github.com/moy/Git-Mediawiki/wiki
--
2.9.0
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] add documentation to mw-to-git
2016-07-04 22:27 [PATCH] add documentation to mw-to-git Alexandru Zbarcea
@ 2016-07-05 13:09 ` Matthieu Moy
0 siblings, 0 replies; 2+ messages in thread
From: Matthieu Moy @ 2016-07-05 13:09 UTC (permalink / raw)
To: Alexandru Zbarcea
Cc: git, Benoit Person, Célestin Matte, David Aguilar,
Elia Pinto, Guillaume Sasdy, Jeff King, Jeremie Nikaes,
Jonathan Nieder, Junio C Hamano, Masanari Iida, NGUYEN Kim Thuat,
Pavel Volek, Simon Cathebras, Stefano Lattarini
Hi, and thanks for your contribution.
Alexandru Zbarcea <alexz@apache•org> writes:
> 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).
> +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/
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2016-07-05 13:11 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-07-04 22:27 [PATCH] add documentation to mw-to-git Alexandru Zbarcea
2016-07-05 13:09 ` Matthieu Moy
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox