On 10/15/2010 6:11 PM, Geert Janssens wrote:
On Friday 15 October 2010, Thomas Bullock wrote:
Hi Geert,
Thank you very much for your offer. I too would like the information to be
available as soon as possible for general use by any interested persons.
Your putting it into a wiki would relieve me of a felt (on my side)
pressure to get this done. It is a kind and appreciated offer. I could
send you a copy of the file if you do not have one available. Just tell
me.
I still had the file around in my list messages. See
http://wiki.gnucash.org/wiki/Documentation_Update_Instructions
for the result in wiki format.
For your reference, here's a very short summary of (most of) what I did:
* titles: surround with ==...==
* subtitles are created by surrounding them with one additional = per
sublevel, so for example first subtitles will be ===...===
* numbered lists: replace "1. ", "2. ",... with "#"
* Add some bulleted lists by prepending the paragraphs with a "*"
* The # and * additions can be combined to get recursive lists.
* Note that lists are pretty picky about newlines. I removed most of them
inside list paragraphs, otherwise numbering wouldn't add up.
* If you want a newline in a list item, begin the new line with the same
combination of # and * as the previous line and add one ":"
* literal commands: surround with<pre>...</pre> (I also removed the quotes,
they don't add value anymore with the<pre>...</pre> formatting)
* if you wish to indent a paragraph: prepend a colon (":") and make sure to
remove all newlines from that paragraph.
* I removed the -------------- separators. The wiki sections and subsections
markup is clear enough IMO.
* Note that the tables of contents is courtesy of Media wiki. I don't have to
write it.
So far I have not made any changes to the text itself (apart from some
spelling fixes), to make it easier for your to see how it got translated from
plain text to wiki text.
I do have some remarks on what you have written also though:
Step 9: you don't have to list yourself as wanting to be notified explicitly
when you reported the bug. In that case you will automatically be notified.
Notes on step 1: the events you describe here in case subversion is not
installed are very distribution dependent. I think right now it only happens
in very recent distro's (I know for Fedora it will only first appear in the
new Fedora 14). Perhaps it's best to refer the reader to his/her distro
specific application installation tools here to install subversion.
Notes on step 6: your explanation here is a bit misleading. "svn dif" doesn't
contact the online repository. It uses the local working copy's metadata
(which can be found in the hidden directory .svn) to determine what has
changed since the last time you ran svn update. It is the svn update command
that connect to the online repository to retrieve any new changes. So if you
wish to view the changes you made compared to the status of the online
repository, you should start with an svn update, and then run svn diff.
In the same section: you mention "diff -ur". As I mentioned in the mailing
list as well, this won't work in subversion. Instead you should use "svn
diff". ("diff -ur" requires additional parameters to run).
(Forgive me if my writing is a little compact. I should be in bed by now...)
<snip>
If I am not mistaken there is also duplication among the wiki pages which
should be rectified by making them more topical with cross-linking to the
main place treatment of a topic is given.
Yes, there most likely is.
Finally, I think we could have a feature that we could think of as a "site
map". It would be a way for persons to search all aspects of
documentation: Guide, Help, FAQs. Key words and aliases pointing to key
words constitute what I am thinking about. Each key word is a link to a
page. On that page are references to all places where the key word is
discussed, explained, used. This certainly would need for all
documentation catch-up to be completed before it was attempted in earnest
fashion. This last idea really is only a dream at this point. Much, Much
more needs to be done before that is a realistic project.
There are some helpful pages provided automatically by Media wiki, but they
are fairly well hidden. If you click the "Special Pages" link on the left, you
will get a list of pages Mediawiki itself maintains. Of particular interest
here are the "All Pages" page and the "Categories" page. The first is simply
an alphabetical list of all the pages in the wiki, the second a list of pages
ordered by categories. Note that we have to setup the categories ourselves and
there aren't many yet. But that could become a helpful tool to organize the
wiki in the future.
On a different topic while focused on documentation, I note that there are
no page numbers to use as references. That may be explained by using XML
and HTML versions of the manuals. Has anyone ever brought up the idea of
using numbered sections and segments within the chapters' numbering system
as a means of cross-referencing to related ideas within the manuals? To
some extent this seems present, but not as extensively as I think it
might. This idea, if adopted, should be implemented only after the
duplication removal gets completed.
There are some challenges here: some parts of our information are in a wiki,
other parts are in plain html files and some parts are in the xml
documentation. It will be interesting/challenging to come up with an indexing
scheme that works for all these formats.
But as you say, that's a concern for somewhere in the future.
Geert
Thanks very much for getting this into the wiki! I also appreciate your
short tutorial. It will help me greatly as I try to act more
independently. All Much appreciated.
Tom
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
