DocList is a node type whose purpose is to contain a list of other nodes and some associated information. Technically, a doclist is a composition of:
The DocList node type has associated code which allows a doclist instance to be represented in a variety of ways, so doclist editors have some flexibility in making each doclist most usable.
There are two subclasses of doclist: faqlist and tutlist. Only these subclasses are ever instantiated, not doclist. (You can think of doclist as an abstract base class, although technically nothing prevents it from being instantiated.) The subclasses (faqlist and tutlist) are nearly identical in all respects; the main difference have to do with permissions: SiteDocClan have authority to edit faqlists, and Pedagogues have authority to edit tutlists.
The doclist edit page has three parts, contained in two HTML forms. Be careful not to try to make changes in both forms at once, or you will be unhappy when you lose changes you thought you made.
Making changes to the doc list:
When done with your edits to the doc list and/or settings, click either the "Submit below" button above the doc list or the "Submit" button below the Settings.
When editing a doclist, you'll see at the bottom a place to enter arbitrary Settings (name/value pairs). This is presented in a table with a header row like:
Currently, all settings are boolean: you should set them either to 0 or to 1. Note that the default behavior for each setting (i.e. when not explicitly set) varies, and in some cases is context dependent.
Note that a doclist's settings have no effect except when viewing the doclist directly. Any children which are doclists are shown using the parent doclist's settings. That is: if A and B are both doclists with their own settings, and B is a child of A, then B will be rendered with B's settings when viewing B directly, but will be rendered, like A, with A's settings, when viewing A. (I think we need to re-verify this. It doesn't quite sound right.)
Doclists have two render modes: tree and sections. The default is tree mode (sections=0). In this mode, child nodes are represented as links to each node, (except string nodes which are expanded in place). In sections mode (sections=1), child doclist nodes are "expanded", or embedded; and a table of contents, with links to the embedded nodes, is shown at the top.
"Embedding" means that when the parent doclist is displayed, the contents of its child nodes will be shown as well. This has two specific, distinct, effects, depending on whether the child node is another doclist-type node or a "regular" node (e.g. a tutorial or sitefaqlet):
Bottom line: You should normally only set sections=1 for upper-level lists in a hierarchy, where only other lists are linked. Lower-level lists which link to content nodes should not (normally) have sections set.
Default = ON! This setting is orthogonal to the tree/sections mode setting.
Shows author of linked non-list nodes. Default = ON for all tutlists, OFF otherwise. Only has effect in tree mode (sections=0).
Show the doctext above the list. Default is OFF, but turned ON for the top-level Tutorials.
For each link, also show a link to its nodetype. Default = ON for users who can edit the doclist, OFF otherwise.
When ON, string (faqstring,tutstring) entries link to the actual string node. When OFF (the default), string entries link directly to the target of the string. Turn this on for debugging string links. Only has effect in tree mode (sections=0).
What about this Show Auto checkbox?
If turned on, an additional column is shown in the Settings table: Auto Set Value. It has something to do with nodeballs and other setting-related features. It is very rarely used, and in the context of doclists it is utterly superfluous and should be ignored. But if you're a curious devil, start with editvars.
A docstring has two parts: a title and a text.
The title should not contain links/shortcuts, as it will be used as link text. It is really is the string node's title: monks can link to the string node by title using this value. Example: [SOPW]
The text is free-form, and can contain links/shortcuts and other markup, as well as plain text.
When editing a docstring, you can edit the title and the text.
When viewing a docstring,
When viewing a doclist which contains a docstring,
When editing a doclist which contains a docstring,
Bottom line: In the context of a doclist, ordinary users will only ever see the docstring's text.
Even the authorized doclist editors will never see the child docstring's title, except when viewing the doclist in Edit mode.
When linked as a node in normal situations (i.e. in the Chatterbox or in a post, rather than in a doclist), docstrings are not treated differently from other nodes. The link text is the docstring's title, and the link links to the docstring node itself. No automatic redirection or anything like that occurs, and the docstring's text is never used in the rendering of the link.