Oliver,
On Sunday, 2016-03-13 12:08:06 +0100, you wrote:
> ...
> * The documentation is maintained online in the wiki exclusively. It
> shouldn't
> be a problem to add the wiki repo as a subrepo of the source repo. By that a
> pull will update the local version of the wiki, too.
No, that shouldn't be the problem.
Currently the problems are in the "*.md" files in the wiki repository
themselves. What I have done so far in my local clone of the wiki re-
pository (using the "mq" extension, so patches are available):
* At the moment the paramount show stopper is a file named
Ubuntu 14.04 specific build & run instructions.md
because files with blanks in their names do not easily (if at all)
lend themselves to being maintained via a makefile. So I took the
liberty to rename this file to "Ubuntu-14.04-HowTo.md" and to update
the one link pointing to it in some other "*.md" file.
* Some URLs in the "*.md" files point to files in
https://bitbucket.org/maproom/qmapshack/wiki/
rather than just to files relative to the current directory. This is
of no concern as long as you are really online. I've dropped this
prefix wherever it occured.
* Most (if not all) local URLs miss the ".html" extension. This is ok
for a webserver (which appends a missing ".html" extension by default)
but does not work locally in a browser, in particular if the current
directory contains both, an "xx.html" and an "xx.md" file. So I added
the ".html" extensions wherever they were missing.
* Some URLs contain "#..." suffixes referring to local header identifi-
ers in the target files. However, most of these suffixes in the URLs
start with the string "markdown-header-", while the header identifiers
defined in the "<h*>" tags are missing this additional string. So I
removed these "markdown-header-" prefixes.
* Most "*.md" files are defining two links, "Home" and "Manual" in their
first lines. Some "*.md" files are missing these links, even though
they would make perfect sense there. So I added them where meaning-
ful.
* Wanting to read the current documentation "top down" like a book is
rather difficult: you have to remember exactly where you are, click
the "Manual" link and then manually select the link in the current
page just below the one where you've just been. I wrote a simple
script "NavBar.sh" which extracts the sequence of files from the vari-
ous list entities in "DocMain.md" and then supplements the aforementi-
oned "Home" and "Manual" lines in each "*.md" file featuring one with
"Prev" and "Next" links. Besides, it repeats this navigation line at
the bottom of each "*.md" file, so you can easily click your way from
the end of one page to the beginning of the next.
* The wiki respository provides a script "Markdown.pl" which turns out
to be John Gruber's original Perl script dating back to 2004. But
while, say, Whisky improves when left alone for twelve years, software
does not. It does not deteriorate either but this "Markdown.pl"
script simply is unaware of new features meanwhile introduced into the
Markdown notation, in this case notably "Table of Contents" ("TOC"),
tables in general, or tripple backticks.
I poked around a bit and found out that Bitbucket is using Python's
"Markdown" module and that they are using it in "save mode". This
means that French accented characters or German umlauts in the source
texts must not be specified as "&eacut;" or "ä", because in "save
mode" Markdown would convert this to "&auml;" and "&eacut;",
respectively in the HTMLfiles, causing the browser to again display
"ä" and "&eacut;". Therefore all "*.md" source files in the wiki
repository successfully work around this problem by directly specify-
ing these special characters in UTF-8 notation. This works when view-
ing the documentation online at the Bitbucket webserver but may fail
locally, if the defaul encoding expected by your browser is different
from UTF-8.
So I wrote a small script "DocMake.sh" which first sends a HTML "<me-
ta>" tag to standard output specifying the encoding as UTF-8, before
it causes Python's Markdown module to load all necessary Markdown ex-
tensions and then to process the input file in "save mode".
Finally, I wrote a small makefile which allows you to forget all these
gory details.
* What's still missing is a file "README.txt" explaining the new requir-
ement of Python's Markdown module and explaining in more detail how to
use the makefile.
Problems to be solved by the product maintainers:
* There's at least one file, "ReportBugs.md", which is not referenced by
any others of the "*.md" files.
* One file has escaped from the wiki repository and now lives at
https://bitbucket.org/maproom/qmapshack/raw/tip/nsi/HOWTO-BUILD.md
where it is not even converted to HTML. The link to this file can be
found in "DocMain.md" in section "Developer & Translators". However,
apart from moving this file back into the wiki repository and perhaps
renaming it a bit, in my opinion the link pointing to this file should
be moved to section "Windows" in file "DocGetQMapShack.md" and should
there replace or supplement the references to files "nsi/3rdparty.txt"
and "nsi/HOWTO-BUILD.txt" in the source code repository.
Sincerely,
Rainer
------------------------------------------------------------------------------
Transform Data into Opportunity.
Accelerate data analysis in your applications with
Intel Data Analytics Acceleration Library.
Click to learn more.
http://pubads.g.doubleclick.net/gampad/clk?id=278785231&iu=/4140
_______________________________________________
Qlandkartegt-users mailing list
Qlandkartegt-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/qlandkartegt-users
