Merge pull request #6 from ogobrecht/development

Development

.gitattributes

@@ -0,0 +1 @@
+* text=auto

README.md

@@ -61,7 +61,10 @@ END;
 ```
 **/
 
-END DEMO;
+
+PROCEDURE demo_procedure; /** Only a small description. **/
+
+END demo;
 ~~~
 
 - The converter picks up everything between the keywords PACKAGE, FUNCTION, PROCEDURE, TYPE or TRIGGER and a following PL/SQL multiline comment starting with `/**` and ending with `**/` (the double stars are used to support normal multiline comments)
@@ -81,12 +84,17 @@ Many words... Here the converted output of our example package:
 
 ~~~md
 <!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file tests/demo.pks -->
+<!-- markdownlint-disable MD003 MD012 MD024 MD033 -->
 
 Your Leading Level One Header
 =============================
 
-Package demo
-------------
+- [Package demo](#package-demo)
+- [Function demo_function](#function-demo_function)
+- [Procedure demo_procedure](#procedure-demo_procedure)
+
+
+## Package demo
 
 You can use standard markdown here to describe your package, functions and procedures.
 
@@ -103,8 +111,7 @@ c_demo_name CONSTANT VARCHAR2(30 CHAR) := 'A demo package for PLOC';
 ```
 
 
-Function demo_function
-----------------------
+## Function demo_function
 
 Description of the function.
 
@@ -130,6 +137,17 @@ FUNCTION demo_function (
   p_vc2_param IN VARCHAR2) -- Another parameter description.
 RETURN BLOB;
 ```
+
+
+## Procedure demo_procedure
+
+Only a small description.
+
+SIGNATURE
+
+```sql
+PROCEDURE demo_procedure;
+```
 ~~~
 
 For a bigger example see the following two projects which are using PLOC for the generation of the README.md file:
@@ -395,6 +413,12 @@ to escape the first hash character like so:
 
 ## Changelog
 
+### 0.6.3 - 2021-03-13
+
+- Fixed: TOC links only working with generated HTML header IDs
+- Fixed: TOC Links to overloaded functions and procedures are not working
+- Use pure Markdown for the headers since many Markdown processors automatically generate header IDs - for example in VS Code it is working out of the box and GitHub does it also
+
 ### 0.6.2 - 2020-10-10
 
 - Fixed: Add a markdownlint configuration on top of each generated file to get no warnings for rules MD003, MD012, MD033 (also see issue [#5](https://github.com/ogobrecht/ploc/issues/5))
@@ -403,7 +427,6 @@ to escape the first hash character like so:
 
 - Fixed: Escaped SQL\*Plus special characters are now replaced globally
 
-
 ### 0.6.0 - 2018-06-20
 
 - Improved generated document structure
@@ -412,34 +435,29 @@ to escape the first hash character like so:
 - PLOC does now unescape escaped special SQL\*Plus characters (see section "SQL\*Plus Special Characters")
 - Changed minimum number of items to render a TOC from 4 to 3
 
-
 ### 0.5.0 - 2018-12-23
 
 - Add "Do not edit..." message to generated files
 - Add `debug` param to CLI for parsed arguments
 - Improved README regarding glob patterns
 - Internal renamings
 
-
 ### 0.4.1 - 2018-12-18
 
 - Fixed: parsing regex breaks when keywords `package`, `function`, `procedure`, `trigger` or `type` found in a signature (not the starting one, sure, but in a line comment or type declaration)
   - example with two problems: `demo_param my_table.my_column%TYPE --A cool function param`
 - New (manual) test script
 
-
 ### 0.4.0 - 2018-12-15
 
 - Add CLI
 - Add TOC to README
 - Changelog back into the README (feels more natural since we have now a TOC here)
 
-
 ### 0.3.2 - 2018-11-25
 
 Docs only: Corrections to the readme and an additional changelog file.
 
-
 ### 0.3.1 - 2018-11-21
 
 After some private usage and the initial push to npmjs.com here the first public release.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ploc",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "PL/SQL code to doc converter",
   "main": "ploc.js",
   "bin": {

ploc-cli.js

@@ -4,7 +4,7 @@ var fs = require('fs');
 var glob = require('glob');
 var ploc = require('./ploc.js');
 
-// util for parsing arguments: we reuse and extend ploc attributes here
+// Util for parsing arguments: We reuse and extend ploc attributes here.
 ploc.utils.parseCliArgs = require('minimist');
 ploc.opts.cliArgs = {
   string: ["in", "out"],
@@ -22,7 +22,7 @@ ploc.opts.cliArgs = {
   }
 };
 
-// cli help text
+// cli help text.
 ploc.opts.cliHelp = [
   '',
   'Usage: ploc [options]',
@@ -50,7 +50,7 @@ ploc.opts.cliHelp = [
   '',
 ].join('\n');
 
-// utility to calculate one out file path from an in file path and an out file pattern
+// Utility to calculate one out file path from an in file path and an out file pattern.
 ploc.utils.getOutFilePath = function (inFilePath, outFilePattern) {
   var folder, file, match;
   var regexp = /(.*(?:\\|\/)+)?((.*)(\.([^?\s]*)))\??(.*)?/i;
@@ -64,16 +64,16 @@ ploc.utils.getOutFilePath = function (inFilePath, outFilePattern) {
   - $6: variables
   */
 
-  // extract folder and file from inFilePath for replacements of {folder} and {file} in outFilePattern
+  // Extract folder and file from inFilePath for replacements of {folder} and {file} in outFilePattern.
   match = inFilePath.match(regexp);
   folder = match[1] || '';
   file = match[3];
 
-  // do the final replacements and return
+  // Do the final replacements and return.
   return outFilePattern.replace('{folder}', folder).replace('{file}', file);
 }
 
-// utility to process all files for the provided in and out file patterns
+// Utility to process all files for the provided in and out file patterns.
 ploc.utils.files2docs = function (inFilePattern, outFilePattern) {
   var outFilePath;
   var options = {
@@ -87,26 +87,26 @@ ploc.utils.files2docs = function (inFilePattern, outFilePattern) {
       fs.writeFileSync(
         outFilePath,
         '<!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file ' + inFilePath + ' -->\n' +
-        '<!-- markdownlint-disable MD003 MD012 MD033 -->\n\n' +
+        '<!-- markdownlint-disable MD003 MD012 MD024 MD033 -->\n\n' +
         ploc.getDoc(fs.readFileSync(inFilePath, 'utf8'))
       );
     });
   })
 };
 
-// parse cli arguments
+// Parse cli arguments.
 var args = ploc.utils.parseCliArgs(process.argv.slice(2), ploc.opts.cliArgs);
 
-// write back minumum items for toc, as this is later used internally by ploc.getDoc
+// Write back minumum items for toc, as this is later used internally by ploc.getDoc.
 ploc.opts.minItemsForToc = args.toc;
 
-// print help, if options -h or --help were provided
+// Print help, if options -h or --help were provided.
 if (args.help) {
   console.log(ploc.opts.cliHelp);
 } else {
-  // otherwise create the docs
+  // Otherwise create the documents.
   if (args.debug) {
     console.log("CLI arguments:\n", args);
   }
   ploc.utils.files2docs(args.in, args.out)
-}
+}