If I understand correctly, you already have all the documentation
content, and you need to place it in a wiki for easier
browsing/searching and updating.
So the main question is how to structure/organize the content.
Let's say all your pages are in the Main/ wikigroup. If you select
another group like Docs/, the below examples should replace "Main/" and
"Main." with "Docs/" and "Docs.".
I would probably start with a large trail (bulleted list) with links to
all your pages, like in the page Main.Index (or Docs.Index):
* [[Introduction]] [[#intro]]
** [[Example Program]]
** [[Installation]]
** [[Licence]]
* [[Core Language]] [[#core]]
** [[Atoms and Integers]]
*** [[Number Bases]]
*** [[Floats Are Not Exact]]
... and so on
Then I would place a "breadcrumb" trail path in "Main.GroupHeader", or
in "Site.PageActions", or in a specific place in the skin template:
^|[[Main/Index]]|^
This will output links to the parents of the current page, eg if you are
in [[Number Bases]], there will be links to [[Atoms and Integers]],
[[Core Language]] and [[Index]]:
Index > Core Language > Atoms and Integers > Number Bases
At the bottom of the page, or better in Main.GroupFooter, I'd place a
"prev-next" wiki trail:
<|[[Main/Index]]|>
which would output
< Atoms and Integers | Index | Floats Are Not Exact >
so that people can browse up and down the trail in the order of the
index page.
At every main section, in the index page I've added an anchor like
[[#intro]], [[#core]].
Then in these main section pages, I'd include that section of the index
trail like, in Main.CoreLanguage
(:include Main.Index#core:)
This will include the full subtree below "* [[Core Language]]" until the
next anchor.
If you add new pages or reorder the pages in the index trail tree, the
updated section will be included in the main sections.
In the sidebar, I'd only link to the main section links for now(*):
* [[Introduction]]
* [[Core Language]]
* [[Library Routines]]
* [[Other Libraries]]
* [[Recommended Tools]]
* [[Internals]]
* [[Glossary]]
For more information, see:
https://www.pmwiki.org/wiki/PmWiki/WikiStructure
https://www.pmwiki.org/wiki/PmWiki/WikiTrails
https://www.pmwiki.org/wiki/PmWiki/IncludeOtherPages
https://www.pmwiki.org/wiki/PmWiki/GroupHeaders
These may also be useful:
Categories and backlinks, mesh-like cross linking:
https://www.pmwiki.org/wiki/PmWiki/Categories
https://www.pmwiki.org/wiki/Cookbook/Backlinks
WikiGroups, separate website sections, possibly custom configurations,
their own sidebar, etc.:
https://www.pmwiki.org/wiki/PmWiki/WikiGroup
SourceBlock uses GeSHi to highlight code:
https://www.pmwiki.org/wiki/Cookbook/SourceBlock
If you generate many pages, the file storage format in wiki.d is
described here:
https://www.pmwiki.org/wiki/PmWiki/PageFileFormat
or this may be easier, just create the wikitext and let this addon
import it in the correct file format:
https://www.pmwiki.org/wiki/Cookbook/ImportText
Note that a file under wiki.d should have a name that is a regular
PmWiki page name, like "Main.CoreLanguage" (GroupName, dot, PageName,
first letters of words are uppercase, no spaces). The following are
incorrect and may be invisible to PmWiki, or you may have problems when
modifying them: "Core Language" (without group, with space) or
"Main.CoreLanguage.txt" (more than 1 dot) or "main.corelanguage"
(lowercase).
Petko
(*) I said "for now" because there are addons that claim to do expanding
menus. I haven't used these but just tested Cookbook/TrailMenu by Pm and
couldn't make it work reliably. I'll review and hopefully fix it when I
find some time. Or you can try some of the other expanding menu addons.
On 28/09/2019 23:04, Pete Lomax wrote:
I have some documentation that I want to pmwiki-fi.
Currently I use a small program to convert some 1000 internal files to
chm or online html, and can
easily adapt that to do most of the final gruntwork, once I know
precisely what the target is.
The [non-editable] online docs are currently at
http://phix.x10.mx/docs/html/phix.htm
My first stab at the first page is
http://phix.x10.mx/pmwiki/pmwiki.php?n=Main.Wiki
Previously I originally created PCAN (of which the latter is a part)
via web scraping and another one-off
program that I still have somewhere (but will never use in anger
again).
If curious, see https://bitbucket.org/petelomax/phix/src -
specifically docs/phix/makephix.exw, phix.htm, and
docs/phix/src/toc.txt - to fully understand what I already have.
Not particularly worried about the graphics on the first page, and I
already have a geshi widget for code,
it is the lhs menu that needs most help, and I can live without the
hide/unhide feature of that.
Any tips for making the pmwiki version as close as possible to the
online docs would be most appreciated.
_______________________________________________
pmwiki-users mailing list
[email protected]
http://www.pmichaud.com/mailman/listinfo/pmwiki-users
