github.com/dancsecs/gotomd@v0.0.0-20240310162206-65c4805cf510/README.md (about)

     1  <!--- gotomd::Auto:: See github.com/dancsecs/gotomd **DO NOT MODIFY** -->
     2  
     3  <!---
     4      Golang To Github Markdown Utility: gotomd
     5      Copyright (C) 2023, 2024 Leslie Dancsecs
     6  
     7      This program is free software: you can redistribute it and/or modify
     8      it under the terms of the GNU General Public License as published by
     9      the Free Software Foundation, either version 3 of the License, or
    10      (at your option) any later version.
    11  
    12      This program is distributed in the hope that it will be useful,
    13      but WITHOUT ANY WARRANTY; without even the implied warranty of
    14      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    15      GNU General Public License for more details.
    16  
    17      You should have received a copy of the GNU General Public License
    18      along with this program.  If not, see <https://www.gnu.org/licenses/>.
    19  -->
    20  
    21  # Package goToMd
    22  
    23  <!--- gotomd::Bgn::doc::./package -->
    24  ```go
    25  package main
    26  ```
    27  
    28  The gotomd utility provides for the maintenance of github README.MD style
    29  pages by permitting go files, go documentation and go test output to be
    30  included by reference into the github README.md file directly from the Go
    31  code permitting program documentation to be maintained in one place (the Go
    32  code.)
    33  
    34  It can use a template file (```*.md.gtm```) or can maintain a ```*.md``` file
    35  in place.
    36  
    37  Usage of gotomd [-c | -r] [-fvl] [-p perm] [-o outDir] [-U file] [-u uint] path [path...]
    38  
    39  The flags are:
    40  
    41    -c
    42        Reverse operation and remove generated markdown (Cannot be used
    43        with the -r option). Files with a .md extension are expected with
    44        a an .md.gtm file being produced.
    45    -f
    46        Do not confirm overwrite of destination.
    47    -l
    48        Display license before program exits.
    49    -o string
    50        Direct all output to the specified directory. (default ".")
    51    -p int
    52        Permissions to use when creating new file (can only set RW
    53        bits). (default 420)
    54    -r
    55        Replace the *.MD in place (Cannot be used with the -c flag).
    56    -U  string
    57        Collect cpu profile data into named file.
    58    -u  uint
    59        Number of iterations to run when collecting cpu profile information.
    60    -v
    61        Provide more information when processing.
    62  
    63  Directives are placed into the ```*.md.gtm``` file (or directly into the
    64  ```*.md``` document if the replace in place option is given.  These directives
    65  are embedded into HTML style comments.
    66  
    67  ```html
    68  <!--- gotomd::ACTION::PARAMETERS -->
    69  ```
    70  
    71  where ACTION can be one of the following:
    72  
    73  - gotomd::doc::./relativeDirectory/goObject
    74  
    75      Run the go doc command on the object listed from the directory
    76      specified.  The PARAMETER is formatted with the relative directory up
    77      to the last directory separator before the end of the string and the
    78      desired object.  A special object package returns the package
    79      comments.
    80  
    81  - gotomd::dcls::./relativeDirectory/declaredObject ListOfDeclaredGoObjects
    82  
    83      Pull out the declaration for the object and include as a single-line
    84      regardless of how declared in the go code.  The Parameter is a list of
    85      go functions, methods and constants (more object coming) to be included
    86      in a go code block. No comments are included.
    87  
    88  - gotomd::dcln::./relativeDirectory/declaredObject ListOfDeclaredGoObjects
    89  
    90      Pull the declaration and include exactly as declared in the go
    91      source including leading comments.
    92  
    93  - gotomd::dcl::./relativeDirectory/declaredObject ListOfDeclaredGoObjects
    94  
    95      Pull the declaration and include exactly as declared in the go
    96      source.  No Comments are included.
    97  
    98  - gotomd::tst::goTest::./relativeDirectory/testName
    99  
   100      Run go test with the tests listed (or package) to run all tests and
   101      included the output.
   102  
   103  - gotomd::file::./relativeDirectory/fName
   104  
   105      Include the specified file in a code block.
   106  
   107  When expanded in the target file the content will be framed by similar
   108  comments prefixed with 'Bgn' and 'End' as:
   109  
   110  const sztestBgnPrefix = sztestPrefix + "Bgn::"
   111  const sztestEndPrefix = sztestPrefix + "End::"
   112  
   113  A header prefixed with
   114  
   115  const szAutoPrefix = sztestPrefix + "Auto::"
   116  
   117  and a blank line following will be inserted into the output file.  If the
   118  action is not "replace in place" then an addition **DO NOT MODIFY**
   119  warning is included.
   120  <!--- gotomd::End::doc::./package -->