1. The short title
Short titles get displayed in the index.
Think of a short but expressive title for the "short title" field.
If you're editing library docs, this should be just the name of the module you're describing, the "directory" the module is in is already reflected by the index.
Normally, if your module was "abc.foo.bar", you would create a page named "abc", a subpage "foo" and a sub-subpage "bar". We made an exception for Phobos, as it currently only has "std.*" and it doesn't look that good if we split it up.
2. The long title
The long title is the fat heading on the top of each page text. It'll also be used for the HTML title (you can usually see it in your browsers title bar).
The long title will also be used as the chapter name by most exporters.
Don't count the characters in the long title names - make it expressive and - if possible - unique to you site. Cerain exporters can't always display the page index and so the user has to know where he currently is. (Think of a printed pdf file where you don't have an index)
Currently there is also a problem with the CHM files: When you search the CHM file for keywords, you'll get to the correct page. But if you take a look at the help index now, there is no expansion for the current node.
If you're editing library docs, again, use the FULL module name here, with all the dots. If youre splitting inner-module definitions (funtions, classes etc) into several pages, you should also use their full name as their long title. An example: "std.base64.encode" has "encode" as its short title as it already is a sub-page of "std.base64" in the index. The long name is "std.base64.encode".
|