		Search-engine friendly clone of the ACL2 documentation.

Xdoc

Order-subtopics

Control the ordering of subtopics in the XDOC display.

(order-subtopics name order &optional flg) allows you to specify what order the subtopics of name will be presented in. For instance:

(xdoc::order-subtopics mini-tutorial
  (example syntax semantics gotchas references))

By default, XDOC shows subtopics in an alphabetical order. For most reference-manual material this is generally fine. But, especially for tutorial guides, you sometimes intend your topics to be read in some particular order, and alphabetizing things gets in the way.

The order-subtopics command lets you specify the exact subtopic ordering that should be used for a particular topic. One general form is:

(xdoc::order-subtopics parent
  (subtopic1 subtopic2 ... subtopicn))

You don't have to give a complete order. Any subtopics that aren't mentioned will be listed last, in the usual alphabetical order.

A second general form has an optional argument of t. This specifies that the order for unspecified child topics is the order in which the topics were defined, rather than alphabetical.

(xdoc::order-subtopics parent
  (subtopic1 subtopic2 ... subtopicn)
  t)

A special case of that second general form lists no subtopics, thus specifying simply that all children are to be listed in the order in which they were defined.

(xdoc::order-subtopics parent
  nil
  t)

We require parent to refer to some defined topic, but the subtopics don't need to be defined at order-subtopics time. This makes it easy to keep the subtopic ordering close to the defxdoc command, e.g., you can write:

(defxdoc mini-tutorial ...))
(order-subtopics mini-tutorial (example syntax ...))

(defxdoc example ...)
(defxdoc syntax ...)

We do at least warn about undefined topics when you save a manual.