{"thread":{"id":"42776","subject":"[PATCH] add documentation to mw-to-git","startedAt":"2016-07-04T22:34:48Z","lastAt":"2016-07-05T13:11:36Z","messageCount":2,"participants":["Alexandru Zbarcea","Matthieu Moy"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"290805","messageId":"CAGycqjyzXg-FNrp8n9QFE8-uF=OecMyXgHerk_RERiMkpdoz9A@mail.gmail.com","threadId":"42776","inReplyTo":null,"subject":"[PATCH] add documentation to mw-to-git","fromName":"Alexandru Zbarcea","fromEmail":"alexz@apache.org","sentAt":"2016-07-04T22:27:31Z","receivedAt":"2016-07-04T22:34:48Z","isPatch":true,"sender":{"key":"alexz@apache.org","avatar":null},"body":"Signed-off-by: Alexandru Zbarcea \n---\n contrib/mw-to-git/Makefile | 44 ++++++++++++-\n contrib/mw-to-git/git-mediawiki.txt | 100 +++++++++++++++++++++++++++++\n contrib/mw-to-git/git-remote-mediawiki.txt | 7 --\n 3 files changed, 142 insertions(+), 9 deletions(-)\n\ndiff --git a/contrib/mw-to-git/Makefile b/contrib/mw-to-git/Makefile\nindex a4b6f7a..a2b5ed8 100644\n--- a/contrib/mw-to-git/Makefile\n+++ b/contrib/mw-to-git/Makefile\n@@ -12,13 +12,25 @@\n #\n # make install\n\n+prefix ?= /usr/local\n+mandir ?= $(prefix)/share/man\n+man1dir ?= $(mandir)/man1\n+htmldir ?= $(prefix)/share/doc/git-doc\n+\n GIT_MEDIAWIKI_PM=Git/Mediawiki.pm\n SCRIPT_PERL=git-remote-mediawiki.perl\n SCRIPT_PERL+=git-mw.perl\n GIT_ROOT_DIR=../..\n HERE=contrib/mw-to-git/\n\n-INSTALL = install\n+INSTALL ?= install\n+RM ?= rm -f\n+\n+ASCIIDOC = asciidoc\n+XMLTO = xmlto\n+\n+ASCIIDOC_CONF = ../../Documentation/asciidoc.conf\n+MANPAGE_XSL = ../../Documentation/manpage-normal.xsl\n\n SCRIPT_PERL_FULL=$(patsubst %,$(HERE)/%,$(SCRIPT_PERL))\n INSTLIBDIR=$(shell $(MAKE) -C $(GIT_ROOT_DIR)/perl \\\n@@ -26,8 +38,36 @@ INSTLIBDIR=$(shell $(MAKE) -C $(GIT_ROOT_DIR)/perl \\\n DESTDIR_SQ = $(subst ','\\'',$(DESTDIR))\n INSTLIBDIR_SQ = $(subst ','\\'',$(INSTLIBDIR))\n\n+GIT_MEDIAWIKI_DOC := git-mediawiki.1\n+GIT_MEDIAWIKI_XML := git-mediawiki.xml\n+GIT_MEDIAWIKI_TXT := git-mediawiki.txt\n+GIT_MEDIAWIKI_HTML := git-mediawiki.html\n+\n all: build\n\n+doc: $(GIT_MEDIAWIKI_DOC) $(GIT_MEDIAWIKI_HTML)\n+\n+install-doc: install-man install-html\n+\n+install-man: $(GIT_MEDIAWIKI_DOC)\n+ $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)\n+ $(INSTALL) -m 644 $^ $(DESTDIR)$(man1dir)\n+\n+install-html: $(GIT_MEDIAWIKI_HTML)\n+ $(INSTALL) -d -m 755 $(DESTDIR)$(htmldir)\n+ $(INSTALL) -m 644 $^ $(DESTDIR)$(htmldir)\n+\n+$(GIT_MEDIAWIKI_DOC): $(GIT_MEDIAWIKI_XML)\n+ $(XMLTO) -m $(MANPAGE_XSL) man $^\n+\n+$(GIT_MEDIAWIKI_XML): $(GIT_MEDIAWIKI_TXT)\n+ $(ASCIIDOC) -b docbook -d manpage -f $(ASCIIDOC_CONF) \\\n+ -agit_version=$(GIT_VERSION) $^\n+\n+$(GIT_MEDIAWIKI_HTML): $(GIT_MEDIAWIKI_TXT)\n+ $(ASCIIDOC) -b xhtml11 -d manpage -f $(ASCIIDOC_CONF) \\\n+ -agit_version=$(GIT_VERSION) $^\n+\n test: all\n $(MAKE) -C t\n\n@@ -54,4 +94,4 @@ perlcritic:\n perlcritic -5 $(SCRIPT_PERL)\n -perlcritic -2 $(SCRIPT_PERL)\n\n-.PHONY: all test check install_pm install clean perlcritic\n+.PHONY: all doc test check install_pm install install-doc install-man\ninstall-html clean perlcritic\ndiff --git a/contrib/mw-to-git/git-mediawiki.txt\nb/contrib/mw-to-git/git-mediawiki.txt\nnew file mode 100644\nindex 0000000..421fbae\n--- /dev/null\n+++ b/contrib/mw-to-git/git-mediawiki.txt\n@@ -0,0 +1,100 @@\n+git-mediawiki(1)\n+==============\n+\n+NAME\n+----\n+git-mediawiki - Abstracts a Mediawiki as a git repository.\n+\n+\n+SYNOPSIS\n+--------\n+[verse]\n+'git clone' -c = mediawiki::\n+'git fetch' -c =\n+'git mw' help\n+'git mw' preview\n+\n+DESCRIPTION\n+-----------\n+Git-Mediawiki is a project which aims the creation of a gate\n+between git and mediawiki, allowing git users to push and pull\n+objects from mediawiki just as one would do with a classic git\n+repository thanks to 'remote-helpers'.\n+\n+[TIP]\n+For more information, visit the wiki at\n+https://github.com/moy/Git-Mediawiki/wiki\n+\n+[TIP]\n+Limit the pages to be imported. If you don't want to clone the\n+whole wiki, you can import only some pages with:\n+\n+ $ git clone -c remote.origin.pages='A_page Another_page' \\\n+ mediawiki::http://yourwikiadress.com\n+\n+and/or select the content of MediaWiki Categories with:\n+\n+ $ git clone -c remote.origin.categories='First Second' \\\n+ mediawiki::http://yourwikiadress.com\n+\n+\n+COMMANDS\n+--------\n+help::\n+ Display help information about git mw.\n+\n+preview::\n+ Parse and render local file into HTML. Preview a page without\nactually pushing it to the wiki.\n+\n+OPTIONS FOR git\n+-----------------\n+\n+remote..pages::\n+ Imports only the page specified.\n+\n+remote..categories::\n+ Imports only the category page specified.\n+\n+remote..shallow::\n+ Imports only the last revision of a wiki\n+\n+remote..mwLogin::\n+ Login username for the wiki\n+\n+remote..mwDomain::\n+ If your wiki requires specifying a domain when logging in (if you\nuse LDAP authentication for instance), this value represents the\ndomain for your 'remote..mwLogin'.\n+\n+remote..mwPassword::\n+ Login password for the wiki\n+\n+remote..dumbPush::\n+ If 'true', then 'git push' will not touch the MediaWiki metadata,\nand will ask you to reimport history after a successful push,\ntypically with 'git pull --rebase'. For those who know 'git svn', in\nthis mode, 'git push; git pull --rebase' is the equivalent of 'git svn\ndcommit'.\n+\n+remote..fetchStrategy::\n+ by_page::\n+ This is the most efficient method when cloning a small subset\nof a very active wiki. On the other hand, fetching from a wiki with\nlittle activity but many pages is long (the tool has to query every\npage even to say \"Everything up to date\").\n+\n+ by_rev::\n+ Then, git-remote-mediawiki will query the whole wiki for new\nrevisions, and will filter-out revisions that should not be fetched\nbecause they do not touch tracked pages. In this case, for example,\nfetching from an up-to-date wiki is done in constant time (not\nO(number of pages)).\n+\n+AUTHOR\n+------\n+The authors from the git log (alphabetic)::\n+ Benoit Person \n+ Célestin Matte \n+ David Aguilar \n+ Elia Pinto \n+ Guillaume Sasdy \n+ Jeff King \n+ Jeremie Nikaes \n+ Jonathan Nieder \n+ Junio C Hamano \n+ Masanari Iida \n+ NGUYEN Kim Thuat \n+ Pavel Volek \n+ Simon Cathebras \n+ Stefano Lattarini \n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\n\\ No newline at end of file\ndiff --git a/contrib/mw-to-git/git-remote-mediawiki.txt\nb/contrib/mw-to-git/git-remote-mediawiki.txt\ndeleted file mode 100644\nindex 23b7ef9..0000000\n--- a/contrib/mw-to-git/git-remote-mediawiki.txt\n+++ /dev/null\n@@ -1,7 +0,0 @@\n-Git-Mediawiki is a project which aims the creation of a gate\n-between git and mediawiki, allowing git users to push and pull\n-objects from mediawiki just as one would do with a classic git\n-repository thanks to remote-helpers.\n-\n-For more information, visit the wiki at\n-https://github.com/moy/Git-Mediawiki/wiki\n-- \n2.9.0\n"},{"id":"290841","messageId":"vpq7fd0jko7.fsf@anie.imag.fr","threadId":"42776","inReplyTo":"CAGycqjyzXg-FNrp8n9QFE8-uF=OecMyXgHerk_RERiMkpdoz9A@mail.gmail.com","subject":"Re: [PATCH] add documentation to mw-to-git","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-07-05T13:09:44Z","receivedAt":"2016-07-05T13:11:36Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Hi, and thanks for your contribution.\n\nAlexandru Zbarcea writes:\n\n> Signed-off-by: Alexandru Zbarcea \n> ---\n> contrib/mw-to-git/Makefile | 44 ++++++++++++-\n> contrib/mw-to-git/git-mediawiki.txt | 100 +++++++++++++++++++++++++++++\n> contrib/mw-to-git/git-remote-mediawiki.txt | 7 --\n> 3 files changed, 142 insertions(+), 9 deletions(-)\n\nGit-Mediawiki did not contain any in-tree documentation, but already has a\nuser manual:\n\n https://github.com/moy/Git-Mediawiki/wiki/User-manual\n\nI have no objection to moving the documentation in-tree (I even created\nan issue a long time ago but never did it:\nhttps://github.com/moy/Git-Mediawiki/issues/9 ). However, you patch\nalone does not do that: it partly duplicates the existing user-manual,\nand complements it with (useful) things that did not appear there (doc\nfor \"git mw\" and a recap of config variables). I think this is a step in\nthe wrong direction and I'd very much prefer a single documentation.\n\nTwo more things to know about Git-Mediawiki:\n\nhttps://github.com/moy/Git-Mediawiki/issues/34\nMove Git-Mediawiki's code out of git.git's contrib/\n\nEssentially, having the code in git.git's contrib does not bring much\ntoday, and reduces the number of potential contributors. There seems to\nbe a consensus to move it out of git.git and develop it separately.\n\nOne consequence is that asciidoc may not be the best choice as a markup\nformat. Having a format that renders directly on GitHub probably\noverweights the benefit of using the same system as Git. GitHub can\nrender asciidoc, but needs *.asciidoc file names and won't read the\nconfig file AFAIK.\n\nhttps://github.com/moy/Git-Mediawiki/issues/33\nGit-Mediawiki is looking for a new maintainer\n\nGit-Mediawiki was a fun experience, but I'm not using it as much as I\nplaned, and my time budget for it approaches 0, so a new maintainer\nwould be very much welcome (typically to fix issue #34 above).\n\n> +COMMANDS\n> +--------\n> +help::\n> + Display help information about git mw.\n> +\n> +preview::\n> + Parse and render local file into HTML. Preview a page without actually pushing it to the wiki.\n\nBetter write the commands completely like\n\ngit mw help::\n\nto avoid ambiguity with git-remote-mediawiki (which is a separate\ncommand).\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"}]}