Editing DocLists

Background

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:

1. a list of node IDs (via the nodegroup db table) constituting the list itself;
2. a text blob (via the document db table) associated with the list;
3. a set of settings, aka "vars" (via the setting db table) for configuring the list's behavior/appearance.

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.

How to Edit

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:

• To insert an item in the list: Select a new (unused) entry in the list, enter the item's node ID in the right-hand column (the Node ID field) and a non-zero list position in the left-hand column (the Position field). Note: enter only the ID number, e.g. 112233, not markup like [id://112233]!!!


• To change the position of an item in the list: edit the value in its Position field. You'll have to mentally predict what the resulting order will be.


• To delete an item from the list: Change the value in its Position field to 0 (zero).

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.

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.)

Currently available settings with behavior defined:

sections

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):

• Child node IS a doclist: child node appears as a sub-list and the text associated with it displayed in place. This is how the tutorials page is handled.
• Child node IS NOT a doclist: document content of child node is displayed. (This needs to be checked, i dont remember that -demerphq)

When this setting is off, child nodes will be shown simply as links, regardless of their node type.

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.

recurse

Default = ON! This setting is orthogonal to the tree/sections mode setting.

showauthor

Shows author of linked non-list nodes. Default = ON for all tutlists, OFF otherwise. Only has effect in tree mode (sections=0).

showtext

Show the doctext above the list. Default is OFF, but turned ON for the top-level Tutorials.

showtype

For each link, also show a link to its nodetype. Default = ON for users who can edit the doclist, OFF otherwise.

no_string

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.

About DocStrings (tutstrings, faqstrings)

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,

• the page title is the docstring title;
• the page content is the docstring text, rendered.

When viewing a doclist which contains a docstring,

• The entry appears as the docstring's text, rendered. The docstring's title is not visible at all.

When editing a doclist which contains a docstring,

• The entry is shown as a link whose
  • link text is the docstring's title;
  • link target is the docstring node itself (by ID).
• To add a docstring node to a list, enter the docstring's node ID — just like any other doclist entry. (see above)

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.