sourcetoc computes a table of contents for a source code file based on headings found in comments.
/* <TOC> */ >>>> /* <TOC> */
/* </TOC> */ /* Section 1 ................... 8
* Section 1.1 ............... 9
// == Section 1 == * Section 2 ................... 13
// === Section 1.1 === */
/* </TOC> */
...
// == Section 1 ==
// == Section 2 == // === Section 1.1 ===
... ...
// == Section 2 ==
...
sourcetoc supports three styles of headings (wiki, atx (markdown) and html) and a number of programming languages (no strong integration).
Requirements: OCaml ≥ 3.12
To install once do sudo make install.
To get sourcetoc with updates you can do:
git clone https://github.com/nahoj/sourcetoc.git
cd sourcetoc
sudo make lninstall # creates a symlink
And then to update:
cd sourcetoc
git pull
Basic usage:
sourcetoc example.py
This will modify example.py in place after copying it to
example.py~.
In a file, sourcetoc considers one-line comments that start at the
beginning of a line and contain either <TOC> or </TOC> or a
heading. sourcetoc works line by line and does not ignore comment
lines that might have a different meaning because of context
(e.g. inside a multi-line string).
/* == Valid == */
/* == Invalid (multi-line) ==
*/
// == Invalid (space) ==
String s = "
// == Valid (context ignored) ==
";The table of contents is generated from the list of headings and is
inserted between the <TOC> and </TOC> lines. These two must be
unique and appear in this order. Anything that exists between them
(typically a previous version of the TOC) is erased. The rest of the
file is unchanged.
By default sourcetoc expects wiki-style headings (== ... ==). It
also supports atx/Markdown headings (## ... ##) and HTML headings
(<h2>...</h2>). Use --heading-style.
See sourcetoc --help for the full list of options.