For various reasons, I need to maintain a CV, and, moreover, several different versions of it to meet different requirements. At the moment, it's written in Markdown, maintained in a Git repository, and uses Pandoc for conversion to various file formats (e.g., PDF via LaTeX, HTML, Microsoft Word/OOXML, etc.). Unfortunately Pandoc's Markdown does not support conditional inclusion/exclusion of parts of the document (e.g., a switch or if/then/else construct). I'm faced with the prospect of maintaining several different files, and of manually migrating changes between them - a good recipe for mistakes. A Web search reveals that one solution is to set up a preprocessor to perform the conditional inclusion/exclusion operations on the Markdown file. This is cumbersome, but achievable. There may be a Pandoc filter available somewehre that can do the same. Another solution would be to switch the document to LaTeX format. From memory, there's a LaTeX package for conditional inclusion of material in documents. I'm also quite comfortable with LaTeX, so it would be a question of choosing a good LaTeX class for use in CV writing, but which would also convert cleanly to HTML. Latexml seems to be the currently maintained LaTeX to HTML conversion tool. There may be other options that I haven't considered. If anyone on the list has been here before and has suggestions to offer, these would be welcome.
Jason White via luv-main <luv-main@luv.asn.au> writes:
For various reasons, I need to maintain a CV, and, moreover, several different versions of it to meet different requirements.
At the moment, it's written in Markdown, maintained in a Git repository, and uses Pandoc for conversion to various file formats (e.g., PDF via LaTeX, HTML, Microsoft Word/OOXML, etc.).
Unfortunately Pandoc's Markdown does not support conditional inclusion/exclusion of parts of the document (e.g., a switch or if/then/else construct). I'm faced with the prospect of maintaining several different files, and of manually migrating changes between them - a good recipe for mistakes.
I personally use Sphinx for the same purpose. As in the tool that is often used for Python documentation. Similar, but uses restructured text, not markdown. It does have native support for conditional text however, whichout needing a preprocessor. http://sublime-and-sphinx-guide.readthedocs.io/en/latest/conditions.html Having said that, I have never actually used this feature. -- Brian May <brian@linuxpenguins.xyz> https://linuxpenguins.xyz/brian/
Brian May <brian@linuxpenguins.xyz> wrote:
I personally use Sphinx for the same purpose. As in the tool that is often used for Python documentation. Similar, but uses restructured text, not markdown.
Thank you. I had read about it but hadn't looked at the documentation. While LaTeX may turn out to be a better choice in this case (for finer control over the formatting), I have other document-related tasks to consider as well. I'll experiment with the options and determine what solution proves most effective. Knowing multiple markup languages is a good idea.
As a further note to this discussion, AsciiDoc also appears to be interesting, in that it supports conditionals as well as conversion to a variety of formats. The AsciiDoctor implementation seems to be the most current and feature rich.
Alec Clews talk 'Using "old skool" Free tools to easily publish API documentation' from LCA 2018 may be of interest. https://github.com/alecthegeek/doc-api-old-skool - he reprised it at the last LUV meeting. Basically he is using pandoc, graphviz, plantuml, make & m4 to generate documentation, updating interface information from the application source. Using m4 in his style could give you conditional inclusion without much work. On Mon, Apr 9, 2018 at 8:36 AM, Jason White via luv-main <luv-main@luv.asn.au> wrote:
As a further note to this discussion, AsciiDoc also appears to be interesting, in that it supports conditionals as well as conversion to a variety of formats. The AsciiDoctor implementation seems to be the most current and feature rich.
_______________________________________________ luv-main mailing list luv-main@luv.asn.au https://lists.luv.asn.au/cgi-bin/mailman/listinfo/luv-main
Hi, On 07/04/18 02:54, Jason White via luv-main wrote:
For various reasons, I need to maintain a CV, and, moreover, several different versions of it to meet different requirements.
You could extend the concepts of available and enabled as with an Apache2 config... sites-available site-enabled mods-available mods-enabled ala cv1-enabled cv2-enabled ... cv9-enabled You could have a bunch of directories like exim4 split configuration too; classifying each type of information and storing it in a folder for that type. Then for each "type" of CV, you "include" by way of sym linking. You could consider any sections you want / order them with numeric prefix naming with century [or other range types that make sense to you] ranges like http has status codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes Create documents by doing a cat of all files in a directory (for each the CV types). Pipe the output to whatever tool will process the content to product the deliverable. The "content" files can be markdown, asciidoc or whatever you want. Another idea would be to get creative with "tags" as part of file names for the content and use with a grep or similar on filenames to include or exclude content. Just a little brain storming... hope it gives you some ideas that you can use. Cheers A.
On 09.04.18 15:01, Andrew McGlashan via luv-main wrote:
Create documents by doing a cat of all files in a directory (for each the CV types). Pipe the output to whatever tool will process the content to product the deliverable.
And then use make to build one of any set of targets, with the actions for each target being a bunch of cats plus any postprocessing, perhaps. That puts the architecture of all the document variants in one file, in a language designed for building stuff. If current date or whatever needs to be injected, then that's just a redirection to file in an action. With the input section files as target dependencies, not only is the document build specified, but make knows to rebuild the document if any of them have changed.
The "content" files can be markdown, asciidoc or whatever you want.
Another idea would be to get creative with "tags" as part of file names for the content and use with a grep or similar on filenames to include or exclude content.
Perhaps a short awk script which reads a build-spec file, comprising a list of those tags, and scrapes each section to output in turn. If the file of tagged material were read into an associative array with the tags as subscripts, then half a dozen lines would do the job. That would require each build-spec in a separate file. Who needs to muck with yet another fandangle app and learning curve? Erik
participants (5)
-
Andrew McGlashan -
Brian May -
Erik Christiansen -
Jason White -
Rodney Brown