Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
| Artifact ID: | 12424044996bf75e7d2be045295ae0f6244a47f0 |
|---|---|
| Page Name: | How to edit/test tcl man pages |
| Date: | 2015-06-29 12:09:23 |
| Original User: | oehhar |
| Parent: | 9178131b009827127f0da1f36d56776fcad883ac (diff) |
| Next | 8e14e67183c3e8cba99e532eba456d7d37a1e91d |
2015-06-18 Donal K. Fellows posted on the core list the following text:
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.
Some additional resources:
- Mentioned file: man.macros
- Groff help: http://man7.org/linux/man-pages/man7/groff_man.7.html
- A Groff manual: http://www.premvet.co.uk/premvet/faq/roff.html
File structure:
- Commands like .xx always at the beginning of a line.
- Comands like \xx may be within the text.
Some used markup:
- .TP : Paragraph label, start of indented text, text included in html TOC
- \fBText\fR : Bold font
- \fIText\fR : Italic font (\fR (for Roman font) must always follow)
- .RS : Indent paragraph 3 to right start
- .RE : Indent end
- .VS "Text": Mark as new version, "Text" describes version
- .VE "Text": End of mark
- .CS : Source code examples
- .CE : Source code example end
- .SS : Text for a heading
- .SP : Subsection (probably)
- .PP : New line and reset font, margin and indent to default values