From 3b3b1373d9bb29da6edfc9e92e10ad57990d6a28 Mon Sep 17 00:00:00 2001 From: AlphaJack Date: Mon, 5 Feb 2024 13:25:22 +0100 Subject: [PATCH] docs: documented HTML and stdin support --- USAGE.md | 75 +++++++++++++++++++++++++++++------------------------- toc/toc.py | 1 + 2 files changed, 42 insertions(+), 34 deletions(-) diff --git a/USAGE.md b/USAGE.md index fb8d691..959487e 100644 --- a/USAGE.md +++ b/USAGE.md @@ -11,16 +11,18 @@ // ├──┐glob expansion // │ ├── Show line numbers // │ ├── Set a custom comment character +// │ ├── Set a custom file extension +// │ ├── Read from stdin // │ ├── Redirect output to another file // │ ├── Other commands // │ └──┐Exceptional file types // │ ├──┐No comments needed +// │ │ ├── HTML // │ │ ├── Markdown // │ │ ├── Beancount // │ │ └── Perl // │ ├──┐Wrap around comments needed // │ │ ├── CSS -// │ │ ├── HTML and Quarto // │ │ └── OCaml // │ └──┐Compatibility with third-party editors // │ ├── Vim and Emacs @@ -298,6 +300,29 @@ But how could `toc` recognize that `//` is the proper comment character for that Well, thanks to AI[^1] `toc` supports most programming and markup languages, from COBOL to Carbon. In case it doesn't work as expected, you can force the behavior by running `toc -c "//" example.xyz`. +## Set a custom file extension + +You can also force toc to consider an arbitrary file extension by running `toc -e "html" new-file-format.html6`. + +## Read from stdin + +`toc` can read stdin by using `-` as an argument. +You may want to set an extension as well: `curl -s "https://example.com/" | toc -e html -` + +Result: + +```html + +``` + ## Redirect output to another file For testing purposes, you can run `toc -o output.py input.py` to choose a different output file. @@ -313,9 +338,23 @@ You can run `toc -h` for usage info and `toc -v` to read the current version ## Exceptional file types ### No comments needed +For these file types, you don't need to write comments, as `toc` can leverage the language syntax to build the table of contents + +#### HTML + +For HTML files, just use regular headings tags such as `

`, `

` and so on: + +```html + + +

Title

+

Subtitle

+ +``` + #### Markdown -For Markdown files, you don't need to write comments, just organize your sections with one or more `#`: +For Markdown files, just organize your sections with one or more `#`: # Title @@ -399,38 +438,6 @@ For CSS files, you have to wrap your `//` comments between `/*` and `*/`: -#### HTML and Quarto - -For HTML and Quarto files, you have to wrap your `//` comments between ``: - -
- Click to view `example.html` - -```html - - - - - - - - - - - - - -

Title

- - -``` - -
- #### OCaml For OCaml files, you have to wrap your `*` comments between `(*` and `*)`: diff --git a/toc/toc.py b/toc/toc.py index ae04cd4..0a31d15 100644 --- a/toc/toc.py +++ b/toc/toc.py @@ -20,6 +20,7 @@ # │ │ ├── HEADER # │ │ ├──┐BODY # │ │ │ ├── BEANCOUNT AND MARKDOWN +# │ │ │ ├── HTML # │ │ │ ├── PERL # │ │ │ ├── GENERIC # │ │ │ └── PRETTIFY CONNECTORS