doctools_lang_cmdref(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

doctools_lang_cmdref ✨

okay bestie, welcome to the doctools language command reference — that's the doctools_lang_cmdref page from the Documentation tools manual, section 3tcl. This is part 1 of the whole thing, so buckle up, there's more coming. 💖

🌸 SYNOPSIS 🌸

no cap, here's every single command signature, exactly as written, don't touch a character:

arg text

arg_def type name ?mode?

bullet

call args

category text

class text

cmd text

cmd_def command

comment plaintext

const text

copyright text

def text

description

enum

emph text

example text

example_begin

example_end

file text

fun text

image name ?label?

include filename

item

keywords args

lb

list_begin what

list_end

lst_item text

manpage_begin command section version

manpage_end

method text

moddesc text

namespace text

nl

opt text

opt_def name ?arg?

option text

package text

para

rb

require package ?version...?

section name

sectref id ?text?

sectref-external text

see_also args

strong text

subsection name

syscmd text

term text

titledesc desc

tkoption_def name dbname dbclass

type text

uri text ?text?

usage args

var text

vset varname value

vset varname

widget text

💅 DESCRIPTION 💅

So this document right here spells out both the names and the syntax of every command that together make up the doctools markup language, version 1. ✨

Because this is meant to be a reference and not a bedtime story, the commands are listed in alphabetical order and the descriptions are, like, pretty short. ngl.

If you're a beginner, do yourself a favor and go read the way more casually written doctools language introduction first. This page assumes you already know the vibe. 🫶

👑 COMMANDS 👑

alphabetical, one by one, no skipping, periodt.

  • arg text — Text markup. The argument text gets marked up as the argument of a command. Main uses: highlighting command arguments inside free-form text, and for the argument parameters of the markup commands call and usage. 🎀
  • arg_def type name ?mode? — Text structure. List element. Argument list. It automatically closes the previous list element. It specifies the data-type of the described argument of a command, its name, and its i/o-mode. That last one is optional, bestie.
  • bullet — Deprecated. Text structure. List element. Itemized list. Go look at item for the canonical command that opens a list item in an itemized list. 🙈
  • call args — Text structure. List element. Definition list. Automatically closes the previous list element. It defines the term as a command and its arguments. The first argument is the name of the command being described by the free-form text that follows, and all the arguments after that are descriptions of that command's arguments. It's expected that the arguments get marked up with arg, method, option etc., as appropriate, and that the command itself gets marked up with cmd. And it's expected that the formatted term isn't just printed in place — it also shows up in the table of contents of the document, or the synopsis, depending on the output format. 👑
  • category text — Document information. Anywhere. This command registers its plain text arguments as the category this document belongs to. If you use this command multiple times, the last value you specified is the one that wins.
  • class text — Text markup. The argument gets marked up as the name of a class. The text may already have other markup applied to it. Main use: highlighting class names in free-form text. ✨
  • cmd text — Text markup. The argument text gets marked up as the name of a Tcl command. The text may have other markup already applied to it. Main uses: highlighting commands in free-form text, and for the command parameters of the markup commands call and usage.
  • cmd_def command — Text structure. List element. Command list. Automatically closes the previous list element. The argument specifies the name of the Tcl command to be described by the list element. In the output it's expected to be marked up as if it had been formatted with cmd. 💅
  • comment plaintext — Text markup. The argument text gets marked up as a comment standing outside of the actual text of the document. Main use is in free-form text.
  • const text — Text markup. The argument gets marked up as a constant value. The text may have other markup already applied to it. Main use: highlighting constants in free-form text.
  • copyright text — Document information. Anywhere. This command registers the plain text argument as a copyright assignment for the manpage. When it's invoked more than once, the assignments accumulate. 🫶
  • def text — Text structure. List element. Definition list. Automatically closes the previous list element. The argument text is the term defined by the new list element. Text markup can be applied to it. ✨
  • description — Document structure. This command separates the header from the document body. It implicitly starts a section named "DESCRIPTION" (see the command section). 👑
  • enum — Text structure. List element. Enumerated list. Automatically closes the previous list element.
  • emph text — Text markup. The argument text gets marked up as <em>emphasized</em>. Main use: general highlighting of pieces of free-form text without attaching any special meaning to them. 💖
  • example text — Text structure, text markup. This command marks its argument up as an example. Main use: simple embedding of examples in free-form text. Use this one when the example doesn't need any special markup of its own. Otherwise, use a sequence of example_begin ... example_end.
  • example_begin — Text structure. This command starts an example. All text up until the next example_end belongs to the example. Line breaks, spaces, and tabs have to be preserved literally. Examples cannot be nested. 😭
  • example_end — Text structure. This command closes the example started by the last example_begin.
  • file text — Text markup. The argument gets marked up as a file or directory, i.e. in general a path. The text may have other markup already applied to it. Main use: highlighting paths in free-form text. 🍓
  • fun text — Text markup. The argument gets marked up as the name of a function. The text may have other markup already applied to it. Main use: highlighting function names in free-form text.
  • image name ?label? — Text markup. The argument is the symbolic name of an image, and it gets replaced with the image itself — if a suitable variant is found by the backend. The second argument, if present, gets interpreted as the human-readable description of the image, and it's put into the output in a suitable position, if the format supports that. The HTML format, for example, can place it into the alt attribute of image references. ✨
  • include filename — Templating. The contents of the named file are interpreted as text written in the doctools markup and processed in the place of the include command. The markup in the file has to be self-contained. It is not possible for a markup command to cross the file boundaries. 🚧
  • item — Text structure. List element. Itemized list. Automatically closes the previous list element.
  • keywords args — Document information. Anywhere. This command registers all its plain text arguments as keywords applying to this document. Each argument is a single keyword. If this command is used multiple times, all the arguments accumulate. 👑
  • lb — Text. This command gets replaced with a left bracket. Use it in free-form text. It's required to avoid the interpretation of a left bracket as the start of a markup command. 🎀
  • list_begin what — Text structure. This command starts a list. The exact nature of the list is determined by the argument what of the command. That further determines which commands have to be used to start the list elements. Lists can be nested, i.e. it's allowed to start a new list within a list element. 💅

The allowed types (and their associated item commands) are:

  • arguments — arg_def.
  • commands — cmd_def.
  • definitions — def and call.
  • enumerated — enum
  • itemized — item
  • options — opt_def
  • tkoptions — tkoption_def

Additionally, the following names are recognized as shortcuts for some of the regular types:

  • args — short for arguments.
  • cmds — short for commands.
  • enum — short for enumerated.
  • item — short for itemized.
  • opts — short for options.

And at last, the following names are still recognized for backward compatibility, but are otherwise considered to be deprecated.

  • arg — Deprecated. See arguments.
  • bullet — Deprecated. See itemized.
  • cmd — Deprecated. See commands.
  • opt — Deprecated. See options.
  • tkoption — Deprecated. See tkoptions.
  • list_end — Text structure. This command closes the list opened by the last list_begin command coming before it. 🔚
  • lst_item text — Deprecated. Text structure. List element. Definition list. Go see def for the canonical command that opens a general list item in a definition list. 🙈
  • manpage_begin command section version — Document structure. The command to start a manpage. The arguments are the name of the command described by the manpage, the section of the manpages this manpage resides in, and the version of the module containing the command. All arguments have to be plain text, without markup. 👑
  • manpage_end — Document structure. The command to end a manpage/document. Anything in the document coming after this command is in error. 💀
  • method text — Text markup. The argument text gets marked up as the name of an object method, i.e. a subcommand of a Tcl command. The text may have other markup already applied to it. Main uses: highlighting method names in free-form text, and for the command parameters of the markup commands call and usage. ✨

moddesc text

Document information, and it's a header one bestie 💖. It takes that plain text you hand it and registers it as the short description of the module this manpage lives in. Cute, short, iconic.

namespace text

Text markup ✨. Whatever you pass in gets marked up as a namespace name. It's totally fine if text already has other markup layered on it. Main character use case: making namespace names pop inside free-form text 👑

nl

Deprecated, bestie 😭 Text structure. If you want the canonical way to drop paragraph breaks into your text, go look at para instead. nl is giving legacy energy.

opt text

Text markup 🎀. Marks text up as optional. Already-got-markup text is fine, stack it up. Main use is highlighting optional arguments — peep the arg command for that whole situation.

opt_def name ?arg?

Text structure, and it's a list element 📋. Specifically: an option list. It auto-closes the previous list element for you (no manual cleanup, we love that 💅). You tell it the name and the arguments of the option this list element is describing. Heads up: the name is expected to be marked up with option.

option text

Text markup ✨. Marks the argument up as an option. Other markup already on text? Totally fine. Main use is highlighting options (you might know them as command-switches 🫶) either in free-form text, or in the arguments of the call and usage commands.

package text

Text markup 💜. Marks the argument up as the name of a package. Pre-existing markup is welcome. Main use: making package names stand out in free-form text.

para

Text structure. This is the one that breaks free-form text into paragraphs 🌸. Every time it shows up, it closes the paragraph that came before it and opens a fresh new one for whatever comes next. And if you're craving higher-level structure? That's what sections and subsections are for, bestie.

rb

Text. This command gets replaced with a right bracket. Use it in free-form text. It's required, no cap — otherwise your right bracket gets interpreted as the end of a markup command and everything falls apart 💀.

require package ?version...?

Document information, header energy. This registers its argument package as the name of a package or application that the described package or application requires. You can hand it a whole set of required versions too, if you want. The argument itself can be marked up — the usual suspect there is opt ✨.

section name

Text structure 📚. Kicks off a brand new named document section. The argument has to be plain text, no funny business. It implicitly closes the last paragraph before it, and it also implicitly opens the first paragraph of the new section. Two-for-one 😌.

sectref id ?text?

Text markup 🔗. Formats a reference to the section identified by id. If you don't give it a text, the title of the referenced section gets used in the output. Give it a text, and that's what shows up instead. Your call, main character.

sectref-external text

Text markup 🔗✨. Just like sectref, except the section is assumed to be living in a different document — so it doesn't need to be identified, and no existence checks get made. All it needs from you is the text to format. Low maintenance, highkey convenient.

see_also args

Document information. Works anywhere. This defines direct cross-references to other documents 📎. Each argument is a plain text label identifying the referenced document. Use it more than once and all the arguments just pile up and accumulate. Nothing gets lost 💖.

strong text

Deprecated 😭 Text markup. For the canonical way to emphasize text, go see emph. strong is old news, bestie.

subsection name

Text structure 📑. Starts a new named subsection of a section. Argument must be plain text. It implicitly closes the last paragraph that came before it and implicitly opens the first paragraph of the new subsection. Same iconic energy as section, just one level down.

syscmd text

Text markup 🖥️. Marks the argument up as the name of an external command. Already-marked-up text? Fine, stack it. Main use is highlighting external commands in free-form text.

term text

Text markup 🧠. Marks the argument up as unspecific terminology. Other markup may already be applied, that's chill. Main use is highlighting important terms and concepts in free-form text. Very academic of you, slay.

titledesc desc

Document information, header, and it's optional ✨. Registers that plain text argument as the title of the manpage. If you don't bother, it defaults to whatever value got registered by moddesc. Convenient fr fr.

tkoption_def name dbname dbclass

Text structure, list element, and specifically a widget option list 🎛️. Auto-closes the previous list element, as it should. It specifies:

  • the name of the option as used in scripts,
  • the dbname, i.e. the name used by the option database,
  • and its dbclass, i.e. its type.

And yes — the name is expected to be marked up using option.

type text

Text markup 🏷️. Marks the argument up as the name of a data type. Pre-existing markup is welcome to stay. Main use: highlighting data types in free-form text.

uri text ?text?

Text markup 🌐. The argument gets marked up as a uri (that's a uniform resource identifier, iykyk). It can already have other markup applied, no problem. Main use is highlighting uris in free-form text. Now, if that second text is present, it gets interpreted as the human-readable description of the uri — in other words, its label 🏷️. And if you don't give it an explicit label? The uri is its own label. Self-sufficient queen 💅.

usage args

Text markup. Full description lives at call — this command is syntactically identical, and its expectations for the markup of its arguments are identical too. But here's the plot twist: unlike call, it is not allowed to generate output where this command occurs in the text. The command is silent 🤫. The formatted text may only show up in a different section of the output — a table of contents, or a synopsis, for example — depending on the output format.

var text

Text markup 💜. Marks the argument up as the name of a variable. Other markup already applied? Sure. Main use is highlighting variables in free-form text.

vset varname value

Templating 🧵. In this form, the command sets the named document variable to the specified value. It does not generate output — meaning the command is replaced by the empty string. Silent but productive.

vset varname

Templating 🧵. In this form, the command gets replaced by the value of the named document variable. That's it, that's the whole vibe ✨.

🐛 BUGS, IDEAS, FEEDBACK 💌

This document, and the package it describes, will undoubtedly contain bugs and other problems 😭. That's just how it is, bestie. Please report such in the category doctools of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. And please also report any ideas for enhancements you may have for either the package and/or the documentation — we want them 🫶.

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. That's the format, periodt.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. Do it that way, trust 💅.

👀 SEE ALSO 👀

  • doctools_intro
  • doctools_lang_faq
  • doctools_lang_intro
  • doctools_lang_syntax

🔑 KEYWORDS 🔑

doctools commands, doctools language, doctools markup, markup, semantic markup

📂 CATEGORY 📂

Documentation tools

Copyright (c) 2007-2010 Andreas Kupries <andreas_kupries@users.sourceforge.net>

And that's a wrap on part 2, bestie 🎀✨ this whole thing came from the tcllib source, version 1.0, and it's the doctools_lang_cmdref(3tcl) page 💖 go forth and mark up your docs beautifully, mwah 💅🦋

📦 where this page comes from