[pmwiki-users] Suggestions for online doc wiki please

[Petko Yotov]

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.