"Fossies" - the Fresh Open Source Software Archive

Member "highlight-3.57-x64/src/cli/help.cpp" (12 May 2020, 18017 Bytes) of package /windows/www/highlight-3.57-x64.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "help.cpp": 3.55_vs_3.56.

    1 /***************************************************************************
    2                           help.cpp  -  description
    3                              -------------------
    4     begin                : Die Apr 23 2002
    5     copyright            : (C) 2002-2019 by Andre Simon
    6     email                : a.simon@mailbox.org
    7  ***************************************************************************/
    8 
    9 /*
   10 This file is part of Highlight.
   11 
   12 Highlight is free software: you can redistribute it and/or modify
   13 it under the terms of the GNU General Public License as published by
   14 the Free Software Foundation, either version 3 of the License, or
   15 (at your option) any later version.
   16 
   17 Highlight is distributed in the hope that it will be useful,
   18 but WITHOUT ANY WARRANTY; without even the implied warranty of
   19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   20 GNU General Public License for more details.
   21 
   22 You should have received a copy of the GNU General Public License
   23 along with Highlight.  If not, see <http://www.gnu.org/licenses/>.
   24 */
   25 
   26 #include <iostream>
   27 #include "help.h"
   28 
   29 using namespace std;
   30 
   31 namespace Help
   32 {
   33 void printHelp(const std::string &topic)
   34 {
   35     if (topic=="syntax" || topic=="lang")  {
   36         cout <<"SYNTAX HELP:\n\n";
   37         cout <<"A language definition describes syntax elements of a programming language which\n";
   38         cout <<"will be highlighted by different colours and font types.\n";
   39         cout <<"\n";
   40         cout <<"These definitions are saved as Lua scripts in HL_DATA_DIR/langDefs.\n";
   41         cout <<"File extensions and shebangs are mapped to language definitions in \n";
   42         cout <<"filetypes.conf (see --print-config for the configuration search paths).\n";
   43         cout <<"\n";
   44         cout <<"Apply custom language definitions with --config-file or as absolute path to -S.\n";
   45         cout <<"\n";
   46         cout <<"Use plug-in scripts (--plug-in) to modify syntax parsing and output.\n";
   47         cout <<"\n";
   48         cout <<"Print all installed language definitions with --list-scripts=langs.\n";
   49         cout <<"\n";
   50         cout <<"Exemplary config files:\n";
   51         cout <<"c.lang:      C and C++ syntax file (compiled sources) \n";
   52         cout <<"python.lang: Python syntax file    (script sources)\n";
   53         cout <<"ini.lang:    INI syntax file       (configuration)\n";
   54         cout <<"xml.lang:    XML syntax file       (markup)\n";
   55         cout <<"\n";
   56         cout <<"Refer to README files for configuration syntax and examples.\n";
   57 
   58     } else if (topic=="theme") {
   59         cout <<"THEME HELP:\n\n";
   60         cout <<"A colour theme defines the formatting of recognized syntax elements.\n";
   61         cout <<"\n";
   62         cout <<"These descriptions are saved as Lua scripts in HL_DATA_DIR/themes.\n";
   63         cout <<"\n";
   64         cout <<"Apply custom themes with --config-file or as absolute path to --theme.\n";
   65         cout <<"\n";
   66         cout <<"Use plug-in scripts (--plug-in) to modify the formatting output.\n";
   67         cout <<"\n";
   68         cout <<"Print all installed themes with --list-scripts=themes.\n";
   69         cout <<"\n";
   70         cout <<"Use --base16 to read a theme of the Base16 set or add 'base16/' as prefix.\n";
   71         cout <<"\n";
   72         cout <<"Exemplary config files:\n";
   73         cout <<"darkspectrum.theme: dark canvas (vim) \n";
   74         cout <<"edit-eclipse:       light canvas (IDE)\n";
   75         cout <<"bespin.lang:        dark canvas  (Base16)\n";
   76         cout <<"\n";
   77         cout <<"Refer to README files for configuration syntax and examples.\n";
   78 
   79     } else if (topic=="config") {
   80         cout <<"CONFIG HELP:\n\n";
   81         cout <<"Highlight is configured by a set of Lua scripts and environment variables.\n";
   82         cout <<"See --print-config for the configuration file search paths.\n\n";
   83         cout <<"List of environment variables:\n";
   84         cout <<"HIGHLIGHT_DATADIR: sets the path to highlight's configuration scripts\n";
   85         cout <<"HIGHLIGHT_OPTIONS: may contain command line options, but no input file paths\n\n";
   86         cout <<"Highlight reads TERM and COLORTERM to determine the appropriate default output.\n";
   87     } else if (topic=="plugin" || topic=="plug-in") {
   88         cout <<"PLUG-IN HELP:\n\n";    
   89         cout <<"The plug-in interface allows modifications of syntax parsing, colouring and\n";
   90         cout <<"the document's header and footer.\n";
   91         cout <<"\n";
   92         cout <<"The --plug-in option reads the path of a Lua script which overrides or\n";
   93         cout <<"enhances the settings of theme and language definition files. Plug-ins make\n";
   94         cout <<"it possible to apply custom settings without the need to edit installed\n";
   95         cout <<"configuration files.\n";
   96         cout <<"You can apply multiple plugins by using the --plug-in option more than once.\n";
   97         cout <<"\n";
   98         cout <<"Pass arguments to a plug-in with --plug-in-param.\n";
   99         cout <<"\n";
  100         cout <<"Print all installed themes with --list-scripts=plugins.\n";
  101         cout <<"\n";
  102         cout <<"Exemplary config files:\n";
  103         cout <<"cpp_qt.lua:             Add Qt keywords to C and C++ (simple structure)\n";
  104         cout <<"outhtml_codefold.lua:   Adds code folding for C style languages, and more (advanced)\n";
  105         cout <<"bash_ref_man7_org.lua:  Add man7.org reference links to Bash output (advanced)\n";
  106         cout <<"\n";
  107         cout <<"See README_PLUGINS.adoc for a detailed description and examples of packaged plugins.\n";
  108 
  109     } else if (topic=="test") {
  110         cout <<"SYNTAX TEST HELP:\n\n";
  111         cout <<"The syntax parsing can be validated with test state indicators embedded in comments.\n";
  112         cout <<"These are recognized in files saved as syntax_test_*.\n\n";
  113         cout <<"A test case is defined by two entities: column and expected state.\n";
  114         cout <<"The column is defined by ^ (here) or < (comment start / first column).\n";
  115         cout <<"This indicator points at the tested syntax element of the previous line.\n";
  116         cout <<"The state identifiers match the corresponding HTML output CSS class names.\n\n";
  117         cout <<"See README_TESTCASES.adoc for a detailed description and examples.\n";
  118     }else {
  119         cout<<"USAGE: highlight [OPTIONS]... [FILES]...\n";
  120         cout<<"\n";
  121         cout<<"General options:\n";
  122         cout<<"\n";
  123         cout<<" -B, --batch-recursive=<wc>     convert all matching files, searches subdirs\n";
  124         cout<<"                                  (Example: -B '*.cpp')\n";
  125         cout<<" -D, --data-dir=<directory>     set path to data directory\n";
  126         cout<<"     --config-file=<file>       set path to a lang or theme file\n";
  127         cout<<" -d, --outdir=<directory>       name of output directory\n";
  128         cout<<" -h, --help[=topic]             print this help or a topic description\n";
  129         cout<<"                                  <topic> = [syntax, theme, plugin, config, test]\n";
  130         cout<<" -i, --input=<file>             name of single input file\n";
  131         cout<<" -o, --output=<file>            name of single output file\n";
  132         cout<<" -P, --progress                 print progress bar in batch mode\n";
  133         cout<<" -q, --quiet                    suppress progress info in batch mode\n";
  134         cout<<" -S, --syntax=<type|path>       specify type of source code or syntax file path\n";
  135         cout<<"     --syntax-by-name=<name>    specify type of source code by given name\n";
  136         cout<<"                                  will not read a file of this name, useful for stdin\n";
  137         cout<<" -v, --verbose                  print debug info\n";
  138         cout<<"     --force[=syntax]           generate output if input syntax is unknown\n";
  139         cout<<"     --list-scripts=<type>      list installed scripts\n";
  140         cout<<"                                  <type> = [langs, themes, plugins]\n";
  141         cout<<"     --list-cat=<categories>    filter the scripts by the given categories\n"; 
  142         cout<<"                                  (example: --list-cat='source;script')\n";
  143         cout<<"     --max-size=<size>          set maximum input file size\n";
  144         cout<<"                                  (examples: 512M, 1G; default: 256M)\n"; 
  145         cout<<"     --plug-in=<script>         execute Lua plug-in script; repeat option to\n";
  146         cout<<"                                  execute multiple plug-ins\n";
  147         cout<<"     --plug-in-param=<value>    set plug-in input parameter\n";
  148         cout<<"     --print-config             print path configuration\n";
  149         cout<<"     --print-style              print stylesheet only (see --style-outfile)\n";
  150         cout<<"     --skip=<list>              ignore listed unknown file types\n";
  151         cout<<"                                  (Example: --skip='bak;c~;h~')\n";
  152         cout<<"     --start-nested=<lang>      define nested language which starts input\n";
  153         cout<<"                                  without opening delimiter\n";
  154         cout<<"     --stdout                   output to stdout (batch mode, --print-style)\n";
  155         cout<<"     --validate-input           test if input is text, remove Unicode BOM\n";
  156         cout<<"     --version                  print version and copyright information\n";
  157         cout<<"\n";
  158         cout<<"\n";
  159         cout<<"Output formatting options:\n";
  160         cout<<"\n";
  161         cout<<" -O, --out-format=<format>      output file in given format\n";
  162         cout<<"                                  <format>=[html, xhtml, latex, tex, odt, rtf,\n";
  163         cout<<"                                  ansi, xterm256, truecolor, bbcode, pango, svg]\n";
  164         cout<<" -c, --style-outfile=<file>     name of style file or print to stdout, if\n";
  165         cout<<"                                  'stdout' is given as file argument\n";
  166 
  167         cout<<" -e, --style-infile=<file>      to be included in style-outfile (deprecated)\n";
  168         cout<<"                                  use a plug-in file instead\n";
  169 
  170         cout<<" -f, --fragment                 omit document header and footer\n";
  171         cout<<" -F, --reformat=<style>         reformats and indents output in given style\n";
  172         cout<<"                                  <style> = [allman, gnu, google, horstmann,\n";
  173         cout<<"                                  java, kr, linux, lisp, mozilla, otbs, pico,\n";
  174         cout<<"                                  vtk, ratliff, stroustrup, webkit, whitesmith, user]\n";
  175         cout<<"                                  The user style does not apply a predefined scheme.\n";
  176         cout<<"                                  Use --reformat-option to define the reformatting.\n";
  177         cout<<"     --reformat-option=<opt>    apply an astyle cmd line option (assumes -F)\n";
  178         cout<<" -I, --include-style            include style definition in output file\n";
  179         cout<<" -J, --line-length=<num>        line length before wrapping (see -V, -W)\n";
  180         cout<<" -j, --line-number-length=<num> line number width incl. left padding (default: 5)\n";
  181         cout<<"     --line-range=<start-end>   output only lines from number <start> to <end>\n";
  182 
  183         cout<<" -k, --font=<font>              set font (specific to output format)\n";
  184         cout<<" -K, --font-size=<num?>         set font size (specific to output format)\n";
  185         cout<<" -l, --line-numbers             print line numbers in output file\n";
  186         cout<<" -m, --line-number-start=<cnt>  start line numbering with cnt (assumes -l)\n";
  187         cout<<" -s, --style=<style|path>       set colour style (theme) or theme file path\n";
  188         cout<<" -t, --replace-tabs=<num>       replace tabs by <num> spaces\n";
  189         cout<<" -T, --doc-title=<title>        document title\n";
  190         cout<<" -u, --encoding=<enc>           set output encoding which matches input file\n";
  191         cout<<"                                  encoding; omit encoding info if set to NONE\n";
  192         cout<<" -V, --wrap-simple              wrap lines after 80 (default) characters w/o\n";
  193         cout<<"                                  indenting function parameters and statements\n";
  194         cout<<" -W, --wrap                     wrap lines after 80 (default) characters\n";
  195         cout<<"     --wrap-no-numbers          omit line numbers of wrapped lines\n";
  196         cout<<"                                  (assumes -l)\n";
  197         cout<<" -z, --zeroes                   pad line numbers with 0's\n";
  198         cout<<"     --base16[=theme]           use a theme of the Base16 collection\n";
  199         cout<<"     --delim-cr                 set CR as end-of-line delimiter (MacOS 9)\n";
  200         cout<<"     --isolate                  output each syntax token separately (verbose output)\n";
  201         cout<<"     --keep-injections          output plug-in injections in spite of -f\n";
  202         cout<<"     --kw-case=<case>           change case of case insensitive keywords\n";
  203         cout<<"                                  <case> =  [upper, lower, capitalize]\n";
  204         cout<<"     --no-trailing-nl[=mode]    omit trailing newline. If mode is empty-file, omit\n";
  205         cout<<"                                  only for empty input\n";
  206         cout<<"     --no-version-info          omit version info comment\n";
  207        // cout<<"     --two-pass=<file>          write plug-in with persistent state information\n";
  208        // cout<<"                                  (beta; requires syntax with store instructions)\n";
  209         
  210         cout<<"\n\n";
  211         cout<<"(X)HTML output options:\n";
  212         cout<<"\n";
  213         cout<<" -a, --anchors                  attach anchor to line numbers\n";
  214         cout<<" -y, --anchor-prefix=<str>      set anchor name prefix\n";
  215         cout<<" -N, --anchor-filename          use input file name as anchor prefix\n";
  216         cout<<" -C, --print-index              print index with hyperlinks to output files\n";
  217         cout<<" -n, --ordered-list             print lines as ordered list items\n";
  218         cout<<"     --class-name=<name>        set CSS class name prefix;\n";
  219         cout<<"                                  omit class name if set to NONE\n";
  220         cout<<"     --inline-css               output CSS within each tag (verbose output)\n";
  221         cout<<"     --enclose-pre              enclose fragmented output with pre tag \n";
  222         cout<<"                                  (assumes -f)\n";
  223         cout<<"\n\n";
  224         cout<<"LaTeX output options:\n";
  225         cout<<"\n";
  226         cout<<" -b, --babel                    disable Babel package shorthands\n";
  227         cout<<" -r, --replace-quotes           replace double quotes by \\dq{}\n";
  228         cout<<"     --beamer                   adapt output for the Beamer package\n";
  229         cout<<"     --pretty-symbols           improve appearance of brackets and other symbols\n";
  230         cout<<"\n";
  231         cout<<"\n";
  232         cout<<"RTF output options:\n";
  233         cout<<"\n";
  234         cout<<"     --page-color               include page color attributes\n";
  235         cout<<" -x, --page-size=<ps>           set page size \n";
  236         cout<<"                                  <ps> = [a3, a4, a5, b4, b5, b6, letter]\n";
  237         cout<<"     --char-styles              include character stylesheets\n";
  238         cout<<"\n";
  239         cout<<"\n";
  240         cout<<"SVG output options:\n";
  241         cout<<"\n";
  242         cout<<"     --height                   set image height (units allowed)\n";
  243         cout<<"     --width                    set image width (see --height)\n";
  244         cout<<"\n";
  245         cout<<"\n";
  246         cout<<"Terminal escape output options (xterm256 or truecolor):\n";
  247         cout<<"\n";
  248         cout<<"     --canvas[=width]           set background colour padding (default: 80)\n";
  249         cout<<"\n";
  250         cout<<"\n";
  251         cout<<"GNU source-highlight compatibility options:\n";
  252         cout<<"\n";
  253         cout<<"     --doc                      create stand alone document\n";
  254         cout<<"     --no-doc                   cancel the --doc option\n";
  255         cout<<"     --css=filename             the external style sheet filename\n";
  256         cout<<"     --src-lang=STRING          source language\n";
  257         cout<<" -t, --tab=INT                  specify tab length\n";
  258         cout<<" -n, --line-number[=0]          number all output lines, optional padding\n";
  259         cout<<"     --line-number-ref[=p]      number all output lines and generate an anchor,\n";
  260         cout<<"                                  made of the specified prefix p + the line\n";
  261         cout<<"                                  number  (default='line')\n";
  262         cout<<"     --output-dir=path          output directory\n";
  263         cout<<"     --failsafe                 if no language definition is found for the\n";
  264         cout<<"                                  input, it is simply copied to the output\n";
  265         cout<<"\n";
  266         cout<<"\n";
  267         cout<<"If no in- or output files are specified, stdin and stdout will be used.\n";
  268         cout<<"Since version 3.44, reading from stdin can also be triggered by the '-' option.\n";
  269         cout<<"Default output format: xterm256 or truecolor if appropriate, HTML otherwise.\n";
  270         cout<<"Style definitions are stored in highlight.css (HTML, XHTML, SVG) or\n";
  271         cout<<"highlight.sty (LaTeX, TeX) if neither -c nor -I is given.\n";
  272         cout<<"Reformatting code (-F) will only work with C, C++, C# and Java input files.\n";
  273         cout<<"Wrapping lines with -V or -W will cause faulty highlighting of long single\n";
  274         cout<<"line comments and directives. Using line-range might interfere with multi\n";
  275         cout<<"line syntax elements. Use with caution.\n\n";
  276         cout<<"Run highlight --list-scripts=langs to see all supported syntax types.\n\n";
  277         cout<<"Refer to README files how to apply plug-ins to customize the output.\n\n";
  278         cout<<"Updates and information: http://www.andre-simon.de/\n";
  279     }
  280 }
  281 
  282 }