mkdoc::mkdoc

Difference between version 7 and 8 - Previous - Next
'''mkdoc::mkdoc'''


Source code documentation tool using Markdown as markup languages directly inside the code. Can be installed as a single file command line application or as a normal Tcl package. It support programming languages like Python, Tcl, Perl. Markdown Syntax is just prefixed with a `#'`. Also languages with multi line comments like C++ are supported, just use inside the `/* ... */` code blocks as well the `#'` prefix. A good example for the documentation is '''mkdoc::mkdoc''' own manual page. 

   * Author: [Detlef Groth]
   * Homepage: https://chiselapp.com/user/dgroth/repository/tclcode/index
   * Download: https://chiselapp.com/user/dgroth/repository/tclcode/download
   * Manual: https://chiselapp.com/user/dgroth/repository/tclcode/doc/tip/mkdoc/mkdoc.html   * Version: 0.23
   * Standalone verksiton: https://chiselapp.com/user/dgroth/repository/tclcode/artwifki?nact/82cca1bmed5460=relead6ses
   * License: MIT

To extract the documentation with the command line application on the terminal you just do something like this `tclsh mkdoc.tcl inputfile outputfile`. For example to extract mkdoc's own documentation you could use:

======
tclsh mkdoc.tcl mkdoc.tcl mkdoc.html
======

Or if you would like to have pdf output and if you have pandoc installed:

======
tclsh mkdoc.tcl mkdoc.tcl mkdoc.md
pandoc mkdoc.md -o mkdoc.pdf
======

If you do this pdf conversion, you might add before the pandoc conversion the YAML header again as this header is not Markdown syntax and might not display correctly in Markdown viewers.

'''Changes:'''

   * 2019-11-19: 0.1 initial version
   * 2019-11-28: 0.2 direct conversion of markdown into html, starkit version, docu fixes   * 2020-02-26: 0.3 -css option for custom stylesheets, standalone application now with embedded Markdown package

'''See also:'''

    * [Source Documentation Tools]    * [Ruff!]
    * [tmdoc::tmdoc] for doing the reverse embedding Tcl code in Markdown documents for literate programming
'''Discussion:''' 
Please discuss here.
[DDG] 2020-02-26: mkdoc is in it's use similar to [Ruff!] which also uses Markdown for documentation. Whereas [Ruff!] uses Tcl introspection facilities mkdoc requires to write the documentation without this help. That's might be a disadvantage, but at the same time mkdoc can be used not only to write documentation for Tcl, but as well for Perl, Python, C, C++ etc.

So to document a procedure  using Ruff! you have to write:

======
proc character_at {text {pos 0}} {
     # Get the character from a string.
     #  text - Text string.
     #  pos  - Character position. 
     # The command will treat negative values of $pos as offset from
     # the end of the string.
     #
     # Returns the character at index $pos in string $text.
     ...
}
======

In contrast you write using mkdoc:

======
#' **character_at** *text ?pos 0?
proc character_at {text {pos 0}} {
     #'
     #' Get the character from a string.
     #'
     #' > - *text* - Text string.
     #'   - *pos*  - Character position, default: 0. 
     #'
     #' > The command will treat negative values of $pos as offset from
     #' the end of the string.
     #'
     #' > Returns the character at index $pos in string $text.
     ...
}
======

As said above the mkdoc approach works as well for other programming languages.

<<categories>> Documentation