Feature Request: !rem() Macro

[tajmone]

A new built-in macro: !rem(COMMENT TEXT), does nothing and discards COMMENT TEXT.

Useful for organizing macros code with comments, memos, copyright and license information.

Why? Because markdown doesn't support comments, and using HTML comment (<!-- ... -->) inside macros will cause them to be emited when macros are preloaded, it will pollute the final output with comments that should be bound to the macros themselves, and will cause problems with non HTML output.

Since the last parameter supports fences by default, !rem could be used to create nice headers in macros files, with version info, links, ecc. Just like with any shared code snippet.

[CDSoft]

I also need this macro. I often define it like this: \def(rem)() but it could be builtin.

I'll add it to the next release (this one is easy to code ;-)

Maybe also a command line option to load a file and discard its output to define macros before pandoc headers (to use macros in the document title for instance): pp -rem macro_file file.md | ...

So we need macros to:

• add comments : the parameter is not preprocessed, nothing is emitted
• discard text: the parameter is preprocessed, nothing is emitted (useful to keep side effects such as macro definitions) and a command line parameter to discard the preprocessed content of a file (but keep the macro definitions).

Now I need to find good names for these macros (rem, comment, drop, ???)

[tajmone]

I'm already preloading a file with preprocessed macros, before the actual pandoc document, and it's working fine (but I'm not using pandoc headers, so I'm not worried about any emitted whitespaces). I guess that when using pandoc headers no whitespaces are allowed before the actual document. This is why I prefer to use YAML headers in detached files: they can be placed anywhere and multiple YAML headers are allowed.

This is how the pp-macors library I'm about to publish works:

1. Before running any batch files, a INIT-ENV.bat file (within the macros folder) needs to be loaded once in order to set an env-var used to load the main pp-macro file. It's contents are:

   SET "PP_MACROS_PATH=%~dp0"
   EXIT /B

   It just sets the env-var to whatever the path of the macros folder is, useful if it gets moved around. (this is the env-var that gave me problems when I tried to use it from within pp macros, so I just moved it to batch file).

2. The builder batch file(s) looks like this:

   pp  %PP_MACROS_PATH%macros.pp ^
       FILENAME.md ^
     | pandoc  -f markdown ^
               -t html5 ^
               --standalone ^
               --template=..\..\templates\html5\GitHub\GitHub.html5 ^
               --smart ^
               --normalize ^
               -o FILENAME.html

3. The macros.pp file is the main macro that preloads all other macros. It's contents (at the moment) are:

   !inc(GFM-Alert.pp)
   !inc(GFM-TaskList.pp)
   !inc(Highlight.pp)

   I guess that since all these do emit some whitespace they would break any pandoc headers in FILENAME.md --- so, yes definitely there is a need for a discard-but-preserve-macros option.

For comments macros I would say that !rem() is a fairly straight-forward name, and most people should inuitively guess if (from BASIC or from DOS usage).

As for the command line option to preserve definition and discard contents ... mhhh. Tricky one! Definitely not rem (which usually is associate with a do-nothing at all command). Possible ideas:

1. -peek — because it peeks at definitions without taking any contents.
2. -parse (makes any sense?)
3. -preload / -steal / -grab / -loot
4. -tokenize — because it will keep only tokens/symbols, no other contents.
5. -extract (or -x) — because it extracts symbols, and also because "X" is a rather catch-all symbol.
6. -filter — because it filters out symbols definition only

[CDSoft]

The command line option will be used to load definitions from a macro file (configuration file), so maybe:

• -load file
• -conf file
• -macro file
• -import file (in python, import is the keyword to import a python module)

The comment macro ignores its arguments and emits nothing:

• \comment(...)
• \rem(...) (but in many programming languages, rem is the remainder of the integral division)

The macro that loads definitions from the file (not an external file):

\XXX
~~~~~~~~~~~~~~~~~~~~
some definitions...
~~~~~~~~~~~~~~~~~~~~

No idea for XXX. Maybe \defs or \definitions I'm not sure this one is really useful.

The load macro works as the command line option:

• \load(FILENAME) (equivalent to \XXX(\include(FILENAME)) ?)
• or '\import', '\macro,\conf`

[tajmone]

I like -import file and \comment(): they are clear and unambiguos (and, anyway, it's a "learn it once" thing, it's just good to give it a term easy to remember and spell).

Also \defs and \definitions are good, pity it's not possible to make both short and long version, because \def is already there. So maybe just the long version for this one, to avoid confusion between this and \define? After all this macro is probably going to be used less than \define, so the name lenght shoudn't be an issue.

[CDSoft]

Maybe \quiet instead of \definitions. It parses text quietly without reporting anything. It's more general than just definitions (there may be scripts which output we want to discard).

[tajmone]

Yes, \quiet renders the idea and it's nice.

Possible alternatives: \mute, \muted

[CDSoft]

I've just pushed the release 1.4 with the macros import, comment and quiet and the command line option import.

[tajmone]

Downloaded!

I shall update all macros so I can benefit from these new features, and also update the refrences in my pp tutorial.

Why not attach pre-built binaries to each GitHub release also? This would provide an historical archive of binaries (on cdsoft.fr only latest versions are downloadable).

[tajmone]

Works really nice...

[tajmone]

I've integrated the new features in the macros library with a new commit f15db5f

Now each macros module is much neater and provides useful info for maintainers and users. Example of how the GFM Task List macros module looks now:

!comment(Highlight pp-macros set)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"GFM-TaskList.pp" v1.0.1 (2017-04-09)

A set of macros for enabling GFM task lists within pandoc documents:

-- https://help.github.com/articles/basic-writing-and-formatting-syntax/#task-lists

--------------------------------------------------------------------------------
  OUT FORMAT: html
  OS SUPPORT: all
REQUIREMENTS: CSS defs of "task-list" and "task-list-item" classes (recommended).
              These classes only hide the items' original bullets, therefore
              task lists will work even without them: checkboxes will be shown
              next to the bullet, and look a bit hugly.
--------------------------------------------------------------------------------
(c) Tristano Ajmone 2017, MIT License.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

!define(TaskList)(

<ul class="task-list">
\1
</ul>

)

!define(Task)(
<li class="task-list-item"><input type="checkbox" disabled=""!ifeq[\1][x][ checked=""]>\2</li>
)

[CDSoft]

Why not attach pre-built binaries to each GitHub release also? This would provide an historical archive of binaries (on cdsoft.fr only latest versions are downloadable).

For several reasons.

1. I want to keep the repository small. Once someone committed a PowerPC binary in the repository then every clone was very long and huge (each commit may come with a new binary). So imagine if I put Linux, Windows and Mac binaries...
2. Binaries are not guaranteed to work on any version or distribution of an OS (libraries compatibility issues). I provide binaries apart but I strongly recommend to use the sources only.
3. It's a way to stay away from viruses. A long time ago, I used to generate .exe files for a Python project. I was using Linux and Wine but I got infected, as well as the binaries I uploaded... not nice.

With git we can recreate any version. But most of the time, the user want the latest (and I hope I won't introduce regressions or incompatibilities too often ;-)

[tajmone]

But on GitHub you have the option to include various zip archives of prebuilt binaries with each release (eg: a zip archive for Win x86, one for x86-64, for Linux, Mac OS, ecc.).

These binaries don't end up in the actual repository, they are just links pointing somewhere in GitHub's servers. So they will not be version managed by Git. In fact you can only manage them in the create/edit release menu on GitHub.

Some repos offer just the Windows pre-built binaries, because of the large amounts of tools required to compile on Windows (unlike Linux).

[CDSoft]

Well, I'm too lazy. If it can not be scripted, it will never be uptodate. It would be easier for me to version binaries on my website, just by renaming the archive and providing a quick link to the latest version.

[CDSoft]

See http://cdsoft.fr/pp/download.html (link also added to pp.md).

[tajmone]

Keeping archives on your website is definitely the easiest solution.

Just for the sake of discussion, automating releases could be fully scripted via the GitHub API:

https://developer.github.com/v3/repos/releases/#upload-a-release-asset

POST https://<upload_url>/repos/:owner/:repo/releases/:id/assets?name=foo.zip

I haven't got around to dig into the GH API yet, but it seems that via Travis and the GH API it's possible to automate all the release process so that when a new release tag is created GH takes care of compiling all the different binaries, archive them and publish them as releases assets (and more or less any other automated task one might wish, like updating other repositories connected to the current project, or uploading to an external website, ecc.).

[CDSoft]

Well, my philosophy is to use free standards. My solution relies only on simple web site and git. Github is just a way to share my git repository. I don't want to rely on github specific API. I could use any other git server.