mdoc-assemble(1)

✨ NAME ✨

okay so bestie, welcome to mdoc-assemble(1) — the General Commands Manual page that's literally about mdoc assemble, the lil command that compiles documentation for use in monodoc(1). yes that's the whole name. short, sweet, iconic 💅

---

🌸 SYNOPSIS 🌸

mdoc assemble [OPTIONS]+ PATHS+

---

🦋 DESCRIPTION 🦋

so mdoc assemble creates .tree and .zip files out of your PATHS, and those are for the monodoc(1) documentation browser. giving very much "build my docs pls" energy ✨

the input files must have a supported format, and you tell it which one with the --format option.

the .tree and .zip files get copied into monodoc's sources directory, right alongside a .source file — and that .source file is what monodoc(1) uses to figure out where the documentation should be displayed. main character of the directory tbh 👑

the .source file looks exactly like this:

<?xml version="1.0"?>
<monodoc>
  <node label="LABEL" name="PATH" parent="PARENT">
    <node label="LABEL2" name="PATH2" />
    <!-- ... -->
  </node>
  <source provider="PROVIDER" basefile="BASEFILE" path="PATH" />
  <!-- other <source/> elements -->
</monodoc>

the /monodoc/node node is optional, and it says where in the monodoc tree the documentation should show up. //node elements can be nested to literally any depth to build trees 🌳 and //node/@label is the label that gets displayed inside the monodoc tree.

//node/@name is the name of the monodoc tree node, and you can totally use it as the value of /monodoc/source/@path.

//node/@parent is the node name to use as the parent node. $MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml has a whole list of such names, and this can be any //node/@name value. and bestie, if the //node/@parent value isn't found? it just gets inserted under the "Various" tree node. no drama 🫶

the /monodoc/source/@provider attribute says which format provider should be used when reading the .tree and .zip files — and this must correspond to one of the --format values. no freelancing allowed.

the /monodoc/source/@basefile attribute is the filename prefix for the documentation files. it must be the same prefix you used with the --out parameter. and ngl, there should be no filename extension on this value. none. zero. zip. 🙈

the /monodoc/source/@path attribute is the parent node in monodoc(1)'s tree view where the documentation gets inserted. go peep the $MONO_INSTALL_PREFIX/lib/monodoc/monodoc.xml file for a list of PATH values (those are the //node/@name values), or it can be a //node/@name value from the same .source file. iykyk 💜

once the BASEFILE.source has been written, the docs can be installed so monodoc(1) will display them, with this command:

cp BASEFILE.source BASEFILE.tree BASEFILE.zip \
  `pkg-config monodoc --variable=sourcesdir`

and that's it, you're slaying 💖

---

💅 OPTIONS 💅

• -f, --format=FORMAT — says which documentation format is used within PATHS. the valid FORMAT values include: ecma, ecmaspec, error, hb, man, simple, and xhtml. 👀

peek the FORMATS section below for the tea on these formats.

the default format (if none is specified) is ecma. periodt.

the --format option can be interleaved with PATHS to change the format used for the remaining parameters (until the next --format option shows up), like:

mdoc assemble -o PREFIX A B --format=man C D --format=xhtml E

which will assemble directories A and B with the ecma format, files C and D with the man formt, and directory E with the xhtml format. format switching mid-run, she contains multitudes 🌈

• -o, --out=PREFIX — specify the output file prefix. mdoc assemble creates the files PREFIX.zip and PREFIX.tree. ✨
• -h, -?, --help — display a help message and exit. the classic "help me help you" 🎀

---

👑 FORMATS 👑

the following documentation formats are supported:

🍓 ecma

The Mono ECMA Documentation Format — an XML documentation format with one file per type.

see the mdoc(5) man page for more info.

🧚 ecmaspec

The Mono ECMA Specification Documentation Format. bestie, this is not the format you're looking for — it's the format used to represent the ECMA-334 (C#) standard within monodoc(1). it is not used to display class library documentation. for class library documentation, use the ecma format. ok that's the whole disclaimer 💀

🎀 error

The Error Documentation Format is used to present detailed error messages, and it lives in monodoc(1)'s "C# Compiler Error Reference" tree.

in this format, PATHS is a configuration file, containing this XML:

<ErrorProviderConfig>
    <FilesPath>../../mcs/errors</FilesPath>
    <Match>cs????*.cs</Match>
    <ErrorNumSubstringStart>2</ErrorNumSubstringStart>
    <ErrorNumSubstringLength>4</ErrorNumSubstringLength>
    <FriendlyFormatString>CS{0:0###}</FriendlyFormatString>
</ErrorProviderConfig>

and the elements mean:

• /ErrorProviderConfig/FilesPath — specifies where to look for files.
• /ErrorProviderConfig/Match — specifies the filename pattern to look for within the /ErrorProviderConfig/FilesPath directory.
• /ErrorProviderConfig/ErrorNumSubstringStart — specifies where within the filename the error number starts.
• /ErrorProviderConfig/ErrorNumSubstringLength — specifies how many characters after /ErrorProviderConfig/ErrorNumSubstringStart to use for the error number.
• /ErrorProviderConfig/FriendlyFormatString — specifies the formatting/display of the node in the monodoc(1) tree.

for each file found, it gets converted to HTML with C# syntax coloring applied. fancy 💅

🌈 simple

The Simple Documentation Format file format recursively adds all files and directories underneath PATHS. when displayed, HTML files are displayed as-is. text files get converted into HTML by translating each newline into an HTML <br> element. and no other file type is supported — that's the whole list, no cap.

🌸 man

The Man Page Documentation Format displays groff man pages. (heads up: this is not a full groff parser, and it only handles the man page constructs used within the mono man pages.)

PATHS is a set of XML files containing:

<?xml version="1.0"?>
<manpages>
  <manpage name="NAME" page="FILE" />
</manpages>

there may be multiple //manpage elements within the root /manpage element.

the /manpages/manpage/@name attribute contains the display name for the tree view node, which is also the URL of the man page when using monodoc(1)'s Lookup URL command (before prefixing with a man: prefix). so if /manpages/manpage/@name contains mono(1), then man:mono(1) can be used in the Lookup URL command to view the mono(1) man page. cute right?? 🫶

the /manpages/manpage/@page attribute is the filename that contains the man page. and if this file does not exist, then /manpages/manpage/@name will not be displayed within the tree view. gone, ghosted, not showing up 😭

⭐ xhtml

The XHTML provider interprets PATHS as a Windows Help file XHTML TOC file and looks for referenced documents to create the help source. go get 'em ✨

---

🔥 SEE ALSO 🔥

mdoc(1), mdoc(5), monodoc(1)

---

💌 MAILING LISTS 💌

visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details. come hang out 🫶

---

🌐 WEB SITE 🌐

see also: http://www.mono-project.com/docs/tools+libraries/tools/mdoc/

---

and that's the page bestie!! every flag, every attribute, every weird XML node, all of it. slay 💖

mwah, xoxo — this was mdoc-assemble(1), the General Commands Manual page, signed off as mdoc-assemble(1) 💅🎀✨