**This is automatically generated documentation.** Edit after the "[[#COMMENTS|COMMENTS]]" heading; changes to the main body will be lost. ====== click-pretty ====== pretty-prints a Click configuration in HTML ===== SYNOPSIS ===== **click-pretty** [//options//, //param//=//value// ...] [//routerfile//] > //output//.html\\ **click-pretty** **--dot** [...] [//routerfile//%%\%%] | **dot** -Tpng > //output//.png ===== DESCRIPTION ===== The **click-pretty** tool pretty-prints Click configurations into HTML files, including syntax highlighting and optional indexes; or, optionally, it can output a graph definition suitable for passing to **dot**(1). **Click-pretty** reads a router configuration and, optionally, an HTML-like template file, replaces special tags in the template with HTML code derived from the configuration, and writes the result to the standard output. ===== HTML TEMPLATES ===== **Click-pretty**'s HTML output is based on a template file that contains special HTML-like tags. These tags, which start with a tilde "~", control **click-pretty**'s operation. ==== The config Tag ==== The **%%<%%~config>** tag expands to a pretty-printed version of the router configuration. Various features in the configuration are highlighted with HTML **** tags; the class differs from feature to feature, so you can affect the output with CSS. The classes are: ? **c-cmt** ! Comments. ? **c-kw** ! Keywords. ? **c-cfg** ! Configuration strings. ? **c-cd** ! Element class declarations. ? **c-ed** ! Element declarations. ? **c-err** ! Configuration errors. Other features of the output include: * Anchors marking element declarations and element class declarations. For example, the tag **** encloses the declaration of an element named **X**. * A **span title** attribute encloses every element reference, giving that element's declaration. Thus, a user can find out what class an element has by hovering their mouse over a reference to it. * Similarly, **span title**s explain configuration errors in more detail. * Element class names are linked to element class declarations, for compound elements, or, optionally, to Web documentation, for primitive element classes. See the **-u** option, below. ==== The elements Tag ==== The **%%<%%~elements>** tag expands to an alphabetical list of the elements and/or element classes used in the router configuration. The **entry** attribute determines how elements are rendered; **typeentry** does the same for classes. Inside these attributes, subtags like **%%<%%~name>**, **%%<%%~type>**, and **%%<%%~inputs>** expand to information about the relevant element or type. For example, this **%%<%%~elements>** tag expands to a comma-separated list of the configuration's elements: <~elements entry="<~name>" sep=", "> This one expands to an unordered list of declarations, with element names and type names linked to relevant declarations in the configuration: ==== elements Tag Attributes ==== ? **entry**=//text// ! Sets the text used for each element in the configuration. If this attribute is absent, the **%%<%%~element>** tag's expansion will not mention elements. ? **typeentry**=//text// ! Sets the text used for each element type used by the configuration. If this attribute is absent, the **%%<%%~element>** tag's expansion will not mention element types. ? **sep**=//text// ! Sets the text used to separate entries in the expansion. ? **column**=//which//%%/%%//count// ! If present, //count// should be a number greater than 1, and //which// should be between 1 and //count//. The **%%<%%~element>** tag is expanded, then broken into //count// columns at entry boundaries. Only the //which//th column is printed. ? **configlink**=//text// ! See the **%%<%%~configlink>** subtag below. ? **typeref**=//text// ! See the **%%<%%~typerefs>** subtag below. ? **inputentry**=//text//, **noinputentry**=//text// ! See the **%%<%%~inputs>** subtag below. ? **outputentry**=//text//, **nooutputentry**=//text// ! See the **%%<%%~outputs>** subtag below. ? **inputconnection**=//text//, **noinputconnection**=//text// ! See the **%%<%%~inputconnections>** subtag below. ? **outputconnection**=//text//, **nooutputconnection**=//text// ! See the **%%<%%~outputconnections>** subtag below. ==== Subtags ==== These subtags apply only within **%%<%%~elements>** entries and type entries. ? **<~name [link**=//link//**]>** ! Expands to the current element's name. When the **link** attribute is present, the name is contained in a link pointing at the declaration site within the router configuration or, when //link// equals "type", the element class's Web documentation. ? **<~type [link]>** ! Expands to the current element type's name, or the current element's type-name. When the **link** attribute is present, the name is contained in a link pointing at the the element class's Web documentation. ? **<~config [limit**=//limit//**] [parens]>** ! Elements only. Expands to the current element's configuration string. The result contains at most //limit// characters; if the configuration string was longer, **click-pretty** prints its first //limit// characters, followed by an ellipsis. If **parens** was supplied, non-empty configuration strings are enclosed in parentheses. ? **<~configlink [text**=//text//**]>** ! Elements only. Expands to a link to the element's declaration in the router configuration. The **text** attribute gives the link text; it defaults to the **%%<%%~elements>** tag's **configlink** attribute. ? **<~typerefs [entry**=//text//**] [sep**=//sep//**]>** ! Expands to an alphabetical list of elements in the configuration that have the current element type, separated by //sep//. The **entry** attribute specifies how to render each element; it defaults to the **%%<%%~elements>** tag's **typeref** attribute. ? **<~ninputs [english]>** ! Elements only. Expands to the current element's number of input ports. If **english** was supplied, either "input" or "inputs" follows the number. ? **<~outputs [english]>** ! Elements only. Expands to the current element's number of output ports. If **english** was supplied, either "input" or "inputs" follows the number. ? **<~inputs [entry**=//text//**] [noentry**=//text//**] [sep**=//sep//**]>** ! Elements only. Expands to a list of the element's input ports. The **entry** attribute specifies how to render each port; it defaults to the **%%<%%~elements>** tag's **inputentry** attribute. If the element has no input ports, the **noentry** attribute is used instead, which defaults to the **%%<%%~elements>** tag's **noinputentry** attribute. ? **<~outputs [entry**=//text//**] [noentry**=//text//**] [sep**=//sep//**]>** ! Elements only. Expands to a list of the element's output ports. The **entry** attribute specifies how to render each port; it defaults to the **%%<%%~elements>** tag's **outputentry** attribute. If the element has no output ports, the **noentry** attribute is used instead, which defaults to the **%%<%%~elements>** tag's **nooutputentry** attribute. ? **<~if test**=//text// **[then**=//text//**] [else**=//text//**] [eq**=//text//**]** \\ **'' '''' '''' '''' '''' ''[ne**=//text//**] [gt**=//text//**] [lt**=//text//**] [ge**=//text//**] [le**=//text//**]>** ! Silently expands the **test** attribute, then makes a comparison. If that comparison is true, expands the **then** attribute; otherwise, expands the **else** attribute. The comparison depends on which of the other attributes is present. When **eq** is supplied, the comparison is true if **test**'s expansion equals **eq**'s expansion. **ne** checks for inequality. The **gt**, **lt**, **ge**, and **le** attributes compare strings (or integers) in alphabetical (or numeric) sorting order. A **gt** comparison is true when **test**'s expansion is greater than **gt**'s expansion; similarly, **lt** checks for less than, **ge** for greater-than-or-equal-to, and **le** for less-than-or-equal-to. If none of these attributes are present, the test is true if **test** expands to a nonempty string. ==== Port-Specific Subtags ==== These subtags apply only within **%%<%%~inputs>** and **%%<%%~outputs>** entries. ? **%%<%%~port>** ! Expands to the current port number. ? **%%<%%~processing>** ! Expands to the current port's processing value: either "push", "pull", or (rarely) "agnostic". ? **<~inputconnections [entry**=//text//**] [noentry**=//text//**] [sep**=//sep//**]>** ! Expands to a list of the output ports to which this input port is connected. List entries are separated by //sep//. The **entry** attribute specifies how to render each port; it defaults to the **%%<%%~elements>** tag's **inputconnection** attribute. If the port is not connected to anything, the **noentry** attribute is used instead, which defaults to the **%%<%%~elements>** tag's **noinputconnection** attribute. ? **<~outputconnections [entry**=//text//**] [noentry**=//text//**] [sep**=//sep//**]>** ! Expands to a list of the input ports to which this output port is connected. List entries are separated by //sep//. The **entry** attribute specifies how to render each port; it defaults to the **%%<%%~elements>** tag's **outputconnection** attribute. If the port is not connected to anything, the **noentry** attribute is used instead, which defaults to the **%%<%%~elements>** tag's **nooutputconnection** attribute. ===== OPTIONS ===== If any filename argument is a single dash "-", **click-align** will use the standard input or output instead, as appropriate. ? **-f** //file// \\ **--file** //file// ! Read the router configuration from //file//. The default is the standard input. ? **-e** //expr// \\ **--expression** //expr// ! Use //expr//, a string in the Click language, as the router configuration. ? **-o** //file// \\ **--output** //file// ! Write HTML output to //file//. The default is the standard output. ? **-t** //file// \\ **--template** //file// ! Use //file// as the HTML template file. If no template is specified, **click-pretty** will use a built-in default. ? **-d**//name//=//text// \\ **--define** //name//=//text// ! Defines a new tag named //name//. Occurrences of **%%<%%~**//name//**>** in the template will be replaced with the expansion of //text//. ? **--userlevel** \\ **-k**, **--linuxmodule** ? **-b**, **--bsdmodule** ! Specifies the driver for which the configuration was designed. This is necessary to discover whether ports are push or pull. Usually, you don't have to give any of these options; **click-pretty** will figure out the right answer by looking at the configuration. ? **-u** //url// \\ **--class-docs** //url// ! Web documentation for primitive element classes is available at //url//. The //url// may contain a single "%s", which is replaced with the element class's documentation name. (This is the same as its regular name, unless **=title** was specified in the documentation comment.) URLs specified in elementmap files with $webdoc take precedence over **-u**. ? **--package-docs** //package//=//url// ! Web documentation for primitive element classes in package //package// is available at //url//. The //url// may contain a single "%s", which is replaced with the element class's documentation name. URLs specified in elementmap files take precedence over **--package-docs**. ? **--write-template** ! Output the template unmodified. This is useful for getting a look at the built-in default. ? **--dot** ! Rather than generating HTML, generate a graph definition suitable for input to the **dot**(1) program (part of the **graphviz** suite originally from Bell Labs). Using **--dot**, you can automatically generate a PNG or PostScript graphic showing a picture of the Click configuration, as in "**click-pretty** router.click | **dot** -Tpng >routerpicture.png". ? **-C** //path// \\ **--clickpath** //path// ! Use //path// for CLICKPATH. ? **--help** ! Print usage information and exit. ? **--version** ! Print the version number and some quickie warranty information and exit. ===== FILES ===== ? **CLICKDIR/share/click/elementmap** ! **Click-pretty** uses elementmap files to determine whether ports are push or pull. You can also add '$webdoc URL' lines to elementmap files; **click-pretty** will use that URL for element classes described in that elementmap. As with the **-u** option, a $webdoc URL can contain %%'%%%s', which is replaced with the element class name. ===== AUTHOR ===== Eddie Kohler, kohler@cs.ucla.edu\\ [[http://www.pdos.lcs.mit.edu/click/|http://www.pdos.lcs.mit.edu/click/]] ===== COMMENTS =====