docidx_lang_cmdref(n)

📦 version 2.0, in alpine 3.24, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

✨ NAME ✨

okay bestie, listen up 💖 this is docidx_lang_cmdref — the docidx language command reference, aka the master list of every command the docidx markup language speaks. it's the cheat sheet, the glossary, the whole vibe. 🎀

🌸 SYNOPSIS 🌸

comment plaintext

include filename

index_begin text title

index_end

key text

lb

manpage file text

rb

url url label

vset varname value

vset varname

💅 DESCRIPTION 💅

so here's the tea, bestie: this document spills both the names AND the syntax of every single command that makes up the docidx 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 stay pretty short — no yapping, just facts. ✨

real talk though: if you're a beginner, go read the way more informally written docidx language introduction first. this page is not the place to start, it's the place to look stuff up. periodt. 💜

👑 COMMANDS 👑

🌈 comment plaintext

Index markup. the text argument gets marked up as a comment, and it stands outside the actual text of the document. main use? free-form text, bestie. it's giving "just vibing in the margins". 💬

🌈 include filename

Templating. the contents of the named file get interpreted as text written in docidx markup, and then processed in the place of the include command. 🫶

⚠️ heads up: the markup in that file has to be self-contained. a markup command is not allowed to cross the file boundaries. no sneaky spans across files, nope, not today. 🚫

🌈 index_begin text title

Document structure. this is the command that starts an index. 🎉

the arguments are:

  • text — a label for the whole group of documents the index refers to
  • title — the overall title text for the index, and ngl it's without markup

fun fact: the label is often the name of the package (or extension) that the documents belong to. iykyk. 👑

🌈 index_end

Document structure. the command that ends an index. 🛑

🚨 anything in the document that comes after this command is in error. like, do not pass go, do not collect $200. 💀

🌈 key text

Index structure. this one adds the keyword text to the index. simple, iconic, does exactly what it says. ⭐

🌈 lb

Text. gets replaced with a left bracket. use it in free-form text. it's required so that a left bracket doesn't get interpreted as the start of a markup command. 🧚

⚠️ its usage is restricted to the arguments of other markup commands. stay in your lane, lb. 🙈

🌈 manpage file text

Index structure. adds an element to the index that refers to a document. 📄

the document is specified through the symbolic name file, and the text argument is used to label the reference.

now why symbolic names, you ask? because they preserve the convertibility of this format to any output format, bestie. ✨ the actual name of the file gets inserted by whichever formatting engine you chose, when it converts the input. and that's based on a mapping from symbolic → actual names that you hand to the engine. slay. 💅

🌈 rb

Text. gets replaced with a right bracket. use it in free-form text. required so that a right bracket doesn't get interpreted as the end of a markup command. 🧚

⚠️ same deal as lb: usage is restricted to the arguments of other commands. 🫶

🌈 url url label

Index structure. this is the second command that adds an element to the index. 🔥

the difference? to refer to a document it does not use a symbolic name — instead it uses a (possibly format-specific) url describing the exact location of the document being indexed here. 📍

🌈 vset varname value

Templating. in this form, the command sets the named document variable to the specified value. and no, it does not generate output — the command gets replaced by the empty string. poof. 🌬️

🌈 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 thing. 💜

😭 BUGS, IDEAS, FEEDBACK 😭

ngl bestie, this document and the package it describes will undoubtedly contain bugs and other problems. it's not a vibe, but it's reality. 🙈

please report such in the category doctools of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

also please report any ideas for enhancements you may have for either the package and/or the documentation. we want the glow-up. ✨

when proposing code changes, please provide unified diffs, i.e. the output of diff -u. 👑

💌 note further that attachments are strongly preferred over inlined patches. you can make attachments 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. that's the move. 🫶

🔍 SEE ALSO 🔍

  • docidx_intro
  • docidx_lang_faq
  • docidx_lang_intro
  • docidx_lang_syntax

🎀 KEYWORDS 🎀

docidx commands, docidx language, docidx markup, markup, semantic markup

🌸 CATEGORY 🌸

Documentation tools

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

and that's the whole page, bestie! 🥳 this was docidx_lang_cmdref(n) from the tcllib crew, version 1.0, part of the Documentation tools fam. go forth and mark up your docs with main character energy. mwah 💅✨🦋

📦 where this page comes from