Docs & README.md

Author: bryan-ente

README.md

@@ -218,6 +218,10 @@ protoparser -vvv -output=myfile MeetingYesterday.pml html
 | `-theme=name` | Set export theme (used in HTML/PDF) |
 | `-config=PATH` | Use external config for rendering/export |
 | `--help` | Show CLI help |
+| `--listMacros <dir>` | List all macros in the specified path or builtin macros |
+| `--macroHelp <file_path>` | Show help for a specific macro file |
+| `--listDocs` | List all available documentation files |
+| `--docs <name>` | Show documentation for a specific command or topic |
 
 ### Local development
 

macros/alert.pml

@@ -4,4 +4,9 @@
 <script>alert("{{msg}}")</script>
 
 =docs:
-Shows an alert box with the given message.
+  This macro is used to display an alert message in the browser. It can be useful for notifying users of important information or errors.
+
+  Example usage:
+  @@macro=alert:msg=This is an alert message!
+
+  The `msg` parameter should contain the text you want to display in the alert dialog.

macros/badge.pml

@@ -3,4 +3,11 @@
 =template:
 <span style="background:#{{bg || '333'}};color:#fff;border-radius:999px;padding:0.2em 0.7em;font-size:0.9em">
   {{text}}
-</span>
+</span>
+=docs:
+  This macro is used to create a badge with customizable background color and text. It can be useful for highlighting important information or categorizing content visually.
+
+  Example usage:
+  @@macro=badge:bg=ff0000;text=Important
+
+  The `bg` parameter sets the background color of the badge (default is dark gray), and the `text` parameter specifies the text to display inside the badge.

macros/clicktoreveal.pml

@@ -3,3 +3,10 @@
 =template:
 <button onclick="document.getElementById('rvl').style.display='block'">Reveal contents</button>
 <div id="rvl" style="display:none">{{content}}</div>
+=docs:
+  This macro is used to create a button that reveals hidden content when clicked. It can be useful for displaying additional information or details without cluttering the page.
+
+  Example usage:
+  @@macro=click_reveal:content=This is the hidden content that will be revealed when the button is clicked.
+
+  The `content` parameter should contain the text or HTML you want to display when the button is clicked. The content will initially be hidden and will only appear after the user clicks the "Reveal contents" button.

macros/codeblock_copy.pml

@@ -3,3 +3,10 @@
 =template:
 <pre><code>{{code}}</code></pre>
 <button onclick="navigator.clipboard.writeText(`{{code}}`)">Copy</button>
+=docs:
+  This macro is used to display a block of code with a "Copy" button that allows users to easily copy the code to their clipboard.
+
+  Example usage:
+  @@macro=code_block:code=console.log('Hello, World!');
+
+  The `code` parameter should contain the code you want to display. The "Copy" button will copy the code to the clipboard when clicked.

macros/finance/f_end.pml

@@ -3,3 +3,9 @@
 =template:
   </tbody>
 </table>
+=docs:
+  This macro is used to close a table that was opened with the `f_start` macro.
+  It should be placed at the end of the table to ensure proper formatting and closure.
+
+  Example:
+  @@macro=f_end:x=x

macros/finance/f_entry.pml

@@ -31,3 +31,10 @@
     }
   });
 </script>
+=docs:
+  This macro is used to create a finance entry in a table format. It allows you to specify the title, amount, type (income or expense), category, payment method, and any notes related to the entry.
+
+  Example usage:
+  @@macro=f_entry:title=Job;amount=1500;type=income;category=Job;method=Bank;notes=No provisions
+  or
+  @@macro=f_entry:title=Steam Sale;amount=67.49;type=expense;category=Gaming;method=PayPal;notes=

macros/finance/f_start.pml

@@ -13,3 +13,11 @@
     </tr>
   </thead>
   <tbody>
+
+=docs:
+  This macro is used to start a financial overview table. It sets up the table structure with headers for title, amount, category, method, and notes. You can use this macro at the beginning of your financial entries to create a well-formatted table.
+
+  Example usage:
+  @@macro=f_start:x=x
+
+  After using this macro, you can add entries using the `f_entry` macro and close the table with the `f_end` macro.

macros/finance/f_totals.pml

@@ -22,3 +22,12 @@
     `;
   }
 </script>
+=docs:
+  This macro is used to display the total income, expenses, and balance in a financial overview table. It calculates the totals based on the entries made with the `f_entry` macro and displays them in a summary row at the end of the table.
+
+  Example usage:
+  @@macro=f_totals:x=x
+
+  The totals will be dynamically calculated and displayed in the table, providing a quick overview of your financial status.
+  Use this macro before the `f_end` macro to ensure it appears in the correct place in the table.
+  It is typically placed after all entries have been added using the `f_entry` macro.

macros/quote.pml

@@ -4,4 +4,11 @@
 <blockquote style="border-left:4px solid #999;padding-left:1em;color:#555">
   <em>{{text}}</em>
   <br><small>– {{author}}</small>
-</blockquote>
+</blockquote>
+=docs:
+  This macro is used to create a styled blockquote for quotes. It allows you to display a quote with the author's name in a visually appealing format.
+
+  Example usage:
+  @@macro=quote:text=The only limit to our realization of tomorrow is our doubts of today.;author=Franklin D. Roosevelt
+
+  The `text` parameter contains the quote itself, and the `author` parameter specifies the name of the person who said the quote.