TODO

* Things to Do

 *On This Page*
 {toc:minlevel=2|maxlevel=2}

** Current

**** TODO Add more unit tests

**** TODO Make this a module

*** TODO Get tests working on Windows

Right now the tests shell out to {{echo}} and use a pipe.  This isn't gonna fly cross-platform.

** Staging

*** TODO Implement 'html2confluence' (aka 'html2conflux')

Based on what you've learned about using Mojo::DOM, this should be possible.  Once this is done, we can hook into tools like Pandoc and others to (e.g.) reliably convert Markdown documents to Conflux.

**** TODO Add headers and footers to make output valid

**** TODO Do not add anchor tags to headers unless the TOC macro is used

** Someday Maybe

**** TODO BUG: Quotes in header text lead to broken TOC links

**** TODO Add support for abbrevs?

E.g., type '{NPZ}' everywhere and have it expand to 'New Paltz'.   This will only really be useful for repetitive terms (of which there are a few in technical writing).

I'm not sure how/where to store the abbrevs in the source document.  Need to design that.

**** TODO Implement HTML page breaks

{code}
<p><!-- pagebreak --></p>
{code}

**** TODO Improve the 'include' macro's support for arbitrary wikitext

As of right now (Sun May 15 20:28:46 2016), the 'include' macro can only support paragraphs with inline links/formatting.  It can't do more complex constructs like tables or lists.

Start by investigating and documenting what works and what doesn't, and then fix stuff.

**** TODO Support wrapped text

An idea: maybe this would be easier to do with a first pass that goes through and joins single newlines followed by text up with the previous line (IFF such lines exist).

For example, it would turn this:

{code}
I've just come across a post on Hackernews titled List Comprehensions
in Eight Lines of Clojure. It's definitely a nice little example. But
it also feels kind of unreal, even cheating ;) Because who would
really use such kinds of list comprehensions? It seems to me, that the
whole purpose of this construct is to make the code be concise and
resemble a set-theoretic notation for sets. But here we need to use
them inside a list-comp macro. This actually looks more like just
another iteration construct.
{code}

into this:

{code}
I've just come across a post on Hackernews titled List Comprehensions in Eight Lines of Clojure. It's definitely a nice little example. But it also feels kind of unreal, even cheating ;) Because who would really use such kinds of list comprehensions? It seems to me, that the whole purpose of this construct is to make the code be concise and resemble a set-theoretic notation for sets. But here we need to use them inside a list-comp macro. This actually looks more like just another iteration construct.
{code}

**** TODO Add '--config' flag

This should output the location of the config files (if any).

**** TODO Read settings from config file

There should be a user-level config file, as well as per-directory settings.

**** TODO Should contents of 'htmlcomment' just be dropped from the output?

**** TODO Refactor this ugly bastard

**** TODO Output Pandoc JSON format

**** TODO Note ALL of the differences with Confluence markup in POD


**** TODO Implement underlining

**** TODO Implement toggle-able pretty-printing

**** TODO Implement strikethrough (-FOO-)

**** TODO Implement line breaks (\\)

**** TODO Get 'mailto' links to work

**** TODO Generate a parse tree/AST that can be re-used?

**** TODO Decide on a license for this code

**** TODO Come up with a new name (derived from Confluence?)

Sun May 15 20:17:35 2016:

Right now I'm partial to "Conflux", a synonym.

**** TODO Cherry-pick random bugfixes from alternate branches

**** TODO Can't link to headers in another page

** Archive

**** DONE Devise a better unit testing strategy

Right now the tests are very brittle, and there is no visibility into how they are breaking.

They use {{Test::Simple}} but should start using {{Test::More}}.

The tests are too dependent on the exact string output.  They should probably parse the output into an {{HTML::Tree}} or whatever and check that instead.

----

Sat Aug  6 02:19:41 EDT 2016:

+ Just updated the tests to check HTML::Builder objects against each other rather than strings.  Calling this one done for now, other work will happen on different tickets.

**** DONE Add conditional text support (aka "audiences")

Here's an attempt at a high-level design that (mostly) follows Asciidoc, but tries to keep it "Confluence-ish".

If you have some conditional text, include it in a macro block like the one shown below (or not shown, perhaps).

{code}
{audience:FOO}
Here is some conditional text.
{audience}
{code}

To call {{confluence2html}} and get the first conditional block to appear, run it like this:

{code}
$ confluence2html --audience FOO
{code}

You may also want to provide multiple values to an option.  For example, you may have additional blocks of conditional text.

{code}
{audience:BAR}
Even moar conditional text.
{audience}

{audience:QUUX}
If you are reading this, welcome to the Quux Hierarchy (long may it reign).
{audience}
{code}

To get the first of the above blocks to appear in the output, issue

{code}
$ confluence2html --audience BAR
{code}

To get the second,

{code}
$ confluence2html --audience QUUX
{code}

And to get them both to appear, try

{code}
$ confluence2html --audience BAR --audience QUUX
{code}

{info}
For information on how to actually implement multiple values for a given option, see the section *Options with multiple values* in the {{Getopt::Long}} docs.
{info}

----

***** Testing Conditional Text Support

{audience:FOO}
This block of text will only appear to FOO customers.
{audience}

{audience:BAR}
This block of text will only appear to BAR customers.
{audience}

**** DONE Implement an 'include-like' version of 'code' macro

The macro will look like this:

{code}
{code:file=header-lines.t}
{code}

And its output will look like this:

{code:file=header-lines.t}

Using this macro will require passing the {{--code-samples-directory}} flag on program invocation, so the program knows what directory to look inside for the code file.

The reasons why you might want something like this are explained [in this blog post|https://logicgrimoire.wordpress.com/2015/06/16/include-code-samples-in-markdown-files/].

**** DONE Implement 'include' macro

The macro will look like this:

{code}
{include:file=foo.txt}
{code}

And its output will look like this:

{quote}
{include:file=README}
{quote}

Using this macro will require passing the {{--include-directory}} flag.

**** DONE Wrap list items in UL tags

**** DONE Update build script to massage the Markdown

**** DONE Implement `toc' macro

**** DONE Implement 'htmlcomment' macro

**** DONE Implement header lines (----)

**** DONE Implement blockquotes

**** DONE Fix bug where single quote in a list element causes a line break

**** DONE Evaluate options other than Markdown

**** DONE Support relative links in same page

**** DONE Add command line options

**** DONE Implement ordered lists

**** DONE Make image directory a flag

**** DONE Make base URI for wiki links a flag

{htmlcomment}
Local Variables:
mode: confluence-markup
End:
{htmlcomment}

{htmlcomment}
vim: set ft=confluencewiki:
{htmlcomment}