Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
| Artifact ID: | 9178131b009827127f0da1f36d56776fcad883ac |
|---|---|
| Page Name: | How to edit/test tcl man pages |
| Date: | 2015-06-22 19:54:10 |
| Original User: | oehhar |
| Parent: | 9e8e8296aae50bb34f2e08e6b64faf796a6b61e8 (diff) |
| Next | 12424044996bf75e7d2be045295ae0f6244a47f0 |
Editor
I use emacs but you can use anything you want I suppose. Probably best to not use MS Word; Notepad would be a better choice. :-)
99% of what you might ever want to do when just editing docs can be done without putting a lot of effort into rendering; that's what I usually do.
Check formatting
I check the formatting with 'groff -Tutf8 -man' and with 'make html' ( make html-tcl HTML_INSTALL_DIR=~/test/html) in the unix build tree (which doesn't use groff's -Thtml output mode because that sucks, or at least did a few years ago when I last had time to try it, and which requires an installed tclsh8.6).
There's a release of groff for cygwin apparently (according to Google) so it ought to be usable for you.
Printed output
If you want printed output, you'll get something very good from the -Tps option to groff (and you might want to convert the PS it produces to PDF). While it isn't a primary target for us these days, it's what Tcl's documentation was always supposed to look like.
groff subset
The main thing to beware of is that we actually use a small subset of the full power of groff, augmented with a few of our own macros (defined and "documented" in man.macros). Please avoid using anything too exotic unless you update the HTML generator to support it. Because of this, ‘make html’ is actually the check to use; it's pretty strict about diagnostics.
I don't bother with the winhelp converter these days; the HTML is better (as in “more recently maintained”) and everyone has a reader for the format it produces.
from a core list post 2015-06-18 by Donal K. Fellows