Merge pull request #94 from ZoomRmc/docs
Fabio Cevasco h3rald@h3rald.com
Tue, 19 Sep 2023 12:10:35 -0400
3 files changed,
33 insertions(+),
17 deletions(-)
M
README.md
→
README.md
@@ -9,20 +9,23 @@ _HastyScribe_ is a simple command-line program able to convert [markdown](http://daringfireball.net/projects/markdown) files into HTML files.
## Usage -**hastyscribe** _filename-or-glob-expression_ **[** _<options>_ **]** +**hastyscribe** **[** options **]** _filename-or-glob-expression_ ... Where: -- _filename-or-glob-expression_ is a valid file or [glob](<http://en.wikipedia.org/wiki/Glob_(programming)>) expression that will be compiled into HTML. +- _filename-or-glob-expression_ is a valid markdown file or [glob](<http://en.wikipedia.org/wiki/Glob_(programming)>) expression that will be compiled into HTML. Multiple files and/or globs are supported. - The following options are supported: - - **\-\-field/<field>=<value>** causes HastyScribe to set a custom field to a specific value. - - **\-\-notoc** causes HastyScribe to output HTML documents _without_ automatically generating a Table of Contents at the start. - - **\-\-user-css=<file>** causes HastyScribe to insert the contents of the specified local file as a CSS stylesheet. - - **\-\-user-js=<file>** causes HastyScribe to insert the contents of the specified local file as a Javascript script. - - **\-\-output-file=<file>** causes HastyScribe to write output to a local file (Use [\-\-output-file=-](class:opt) to output to standard output). - - **\-\-watermark=<file>** causes HastyScribe to embed and display an image as a watermark throughout the document. - - **\-\-fragment** causes HastyScribe to output just an HTML fragment instead of a full document, without embedding any image, font or stylesheet. - - **\-\-noembed** causes styles and images not to be embedded. - - **\-\-help** causes HastyScribe to display the usage information and quit. + - **--output-file=<file>** causes HastyScribe to write output to a local file (Use `--output-file=-` to output to standard output). + - **--output-dir=<dir>** or **-d=<dir>** allow you to specify an output directory for the generated HTML files. When used, it will override the `--output-file` option. Please note that this option does not preserve the input directory structure (that, for example, can be observed while traversing glob patterns); all output files will be placed directly in the specified directory. + - **--field/<field>=<value>** causes HastyScribe to define custom field and set it to a specific value. + - **--user-css=<file>** causes HastyScribe to insert the contents of the specified local file as a CSS stylesheet. + - **--user-js=<file>** causes HastyScribe to insert the contents of the specified local file as a Javascript script. + - **--watermark=<file>** causes HastyScribe to embed and display an image as a watermark throughout the document. + - **--notoc** causes HastyScribe to output HTML documents _without_ automatically generating a Table of Contents at the start. + - **--noembed** causes styles and images not to be embedded. + - **--fragment** causes HastyScribe to output just an HTML fragment instead of a full document, without embedding any image, font or stylesheet. + - **--iso** enables HastyScribe to use the ISO 8601 date format (e.g., 2000-12-31) in the footer of the generated HTML documents. + - **--no-clobber** or **-n** prevents HastyScribe from overwriting existing files. If a file with the same name already exists, HastyScribe will issue a warning and will not overwrite it. + - **--help** causes HastyScribe to display the usage information and quit. → For more information, see the [HastyScribe User Guide](https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm)
M
doc/-credits.md
→
doc/-credits.md
@@ -8,7 +8,7 @@ * The beautiful [Mr Bedfort][sudtipos] font, used as the base for the {{hs}} logo.
Special thanks to: -* Philip Wernersbach and Joshua Ellis, for contributing to {{hs}}. +* Philip Wernersbach, Joshua Ellis, and [ZoomRmc](https://github.com/ZoomRmc) for contributing to {{hs}}. * Andreas Rumpf, creator of the amazing [Nim][nim] programming language, used to implement {{hs}}. -> [](class:fa-creative-commons) [](class:fa-creative-commons-by) [](class:fa-creative-commons-nc) [](class:fa-creative-commons-nd) <-
M
doc/-usage.md
→
doc/-usage.md
@@ -4,20 +4,23 @@ {{hs}} is a command-line application that can compile one or more Markdown files into one or more HTML files with the same name(s).
## Command Line Syntax -[hastyscribe](class:cmd) _filename-or-glob-expression_ **[** [_<options>_](class:opt) **]** +[hastyscribe](class:cmd) **[** [_<options>_](class:opt) **]** _filename-or-glob-expression_ ... Where: - * _filename-or-glob-expression_ is a valid file or [glob](http://en.wikipedia.org/wiki/Glob_(programming)) expression that will be compiled into HTML. + * _filename-or-glob-expression_ is a valid markdown file or [glob](http://en.wikipedia.org/wiki/Glob_(programming\)) expression that will be compiled into HTML. Multiple files and/or globs are supported. * The following options are supported: + * [\-\-output-file=<file>](class:opt) causes {{hs}} to write output to a local file (Use [\-\-output-file=-](class:opt) to output to standard output). + * [\-\-output-dir=<dir>](class:opt) or [\-d=<dir>](class:opt) allow you to specify an output directory for the generated HTML files. When used, it will override the [\-\-output-file](class:opt) option. Please note that this option does not preserve the input directory structure (that, for example, can be observed while traversing glob patterns); all output files will be placed directly in the specified directory. * [\-\-field/<field>=<value>](class:opt) causes {{hs}} to set a custom field to a specific value. - * [\-\-notoc](class:opt) causes {{hs}} to output HTML documents _without_ automatically generating a Table of Contents at the start. * [\-\-user-css=<file>](class:opt) causes {{hs}} to insert the contents of the specified local file as a CSS stylesheet. * [\-\-user-js=<file>](class:opt) causes {{hs}} to insert the contents of the specified local file as a Javascript script. - * [\-\-output-file=<file>](class:opt) causes {{hs}} to write output to a local file (Use [\-\-output-file=-](class:opt) to output to standard output). * [\-\-watermark=<file>](class:opt) causes {{hs}} to embed and display an image as a watermark throughout the document. + * [\-\-notoc](class:opt) causes {{hs}} to output HTML documents _without_ automatically generating a Table of Contents at the start. + * [\-\-noembed](class:opt) causes styles and images not to be embedded. * [\-\-fragment](class:opt) causes {{hs}} to output just an HTML fragment instead of a full document, without embedding any image, font or stylesheet. - * [\-\-noembed](class:opt) causes styles and images not to be embedded. + * [\-\-iso](class:opt) enables {{hs}} to use the ISO 8601 date format (e.g., 2000-12-31) in the footer of the generated HTML documents. + * [\-\-no-clobber](class:opt) or [\-n](class:opt) prevents {{hs}} from overwriting existing files. If a file with the same name already exists, {{hs}} will issue a warning and will not overwrite it. * [\-\-help](class:opt) causes {{hs}} to display the usage information and quit. ## Linux and macOS Examples@@ -31,6 +34,11 @@ Executing {{hs}} to compile all [.md](class:ext) files within the current directory:
> %terminal% > ./hastyscribe \*.md + +Executing {{hs}} to compile all [.md](class:ext) files within the current and [in](clas:file) directories and save all the files to directory [out](class:file), preventing any overwrites: + +> %terminal% +> ./hastyscribe --no-clobber -d=out \*.md in/\*.md ## Windows Examples@@ -43,6 +51,11 @@ Executing {{hs}} to compile all [.md](class:ext) files within the current directory:
> %terminal% > hastyscribe.exe \*.md + +Executing {{hs}} to compile all [.md](class:ext) files within the current and [in](clas:file) directories and save all the files to directory [out](class:file), preventing any overwrites: + +> %terminal% +> hastyscribe.exe --no-clobber -d=out \*.md in\\\*.md > %tip% > Tip