documentation.mdwn 2.3 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152
  1. This is going to be the place for:
  2. - Manual pages rendered as HTML
  3. - Library API references and library+program manuals and tutorials
  4. - Parts of READMEs for inlining
  5. - Full code reference and internal/development documents
  6. Links:
  7. - [[manpages]] (generated html)
  8. - [[manual]] (generated html)
  9. - [[readme]] (underlay)
  10. - [[internal]] (can be both)
  11. Update:
  12. I wanted to put all these files under ikiwiki, but all the JS and CSS are going
  13. to be a problem with ikiwiki's html sanitizer. There's no easy safe way to
  14. handle this, other than somehow integrate doxygen with ikiwiki and/or provide
  15. Markdown output for it. There's XML output but I'd need to write an XSL script
  16. or something. Too much for now.
  17. I'm going to work with two things. The 'generated' underlay and a new subdomain
  18. `doc`. It will be a subdomain for all the documents that are not generated from
  19. the wiki's source repo. Ideally these files should be under /srv/www or /var/www
  20. or something like that, but I don't want to waste the space there too much. On
  21. the other hand, Trisquel will come soon. I do have 5 GB free there right now.
  22. The idea is as follows. In the wiki, there are parent pages for the 4 kinds of
  23. documents. Let's take the manuals as an example. There is basically a list of
  24. projects under the manuals page, and each project in the list has its subpage
  25. with version subpages, and special "latest" and "stable" symlinks.
  26. Should these project pages be auto-generated? They can be, using the contents of
  27. their folder, but how do you e.g. determine whether there is a stable version?
  28. How do you tell which one is stable? What if different projects have different
  29. version numbering conventions for this?
  30. Here's an idea. Do maintain a list of versions manually in the wiki, with links
  31. to pages under the new subdomain. For example,
  32. `www.partager.null/projects/sif/documentation` has a list of links to version
  33. specific html pages such as `doc.partager.null/manual/sif/0.1.1/`. The top of
  34. the `doc` subdomain page hierarchy can be generated using `dirlisting` or
  35. something like that, and even have a custom CSS.
  36. The way to get a list of all the docs for a given project is to see its
  37. documentation subpage on the wiki.
  38. Note that new versions already require wiki commits, such as updating the latest
  39. version number and the links to new torrents and tarballs, so adding another
  40. thing to commit is not a big deal.