Re: No one cares?
- Posted by petelomax Sep 19, 2019
- 1186 views
My thoughts:
Heredoc is/was better than nothing, but only just. The manuals it produces are /always/ pretty rubbish. Theoretically there should be a slight benefit from having the examples near to hand for updating, but since that is the number one complaint... You all heard the one about the guy who painted his hallway through the letterbox, to me that sums up exactly just how ridiculous it all is.
If you can get docs out of source onto a wiki, only a madman would attempt to drag updates back into the source code.
In fact, you should delete all that crud lying around in the source code files pretending to be a manual.
You do however need a way to download/extract from the wiki, and build the htm/chm/pdf/whatever, for local use.
Uploading the raw wiki content back into a repository, on a fairly regular basis, and taking full advantage of the diff utils to validate each file as you do so is probably a fine idea, not that there would be much other benefit to maintaining such a repository.
PS: If you dislike chm you can usually just extract the html from them with 7-Zip, and use that (in any browser).
A few additional steps were required for phix.chm, there will be a chm2htm.exw program shipped with 0.8.1 which:
Deletes all files without an extension.
Replaces all `src="/images/` with `src="images/`.
Replaces all javascript:ExternalLink()s (with normal links)
Copies images/ into html/
As for a/my Phix-docs-wiki, my plan is just get page 1 up; then anyone can copy pages from the static files, with any necessary intermediate/breadcrumb pages, and/or maybe a chm2wiki.exw assistant for any drudgework, not that I have started/tried anything yet.
