* The generators originally had two phases, *parse* and *emit*. The *parse*
phase allowed the generator to walk the AST for every document noting things
it would need when emitting output. So the *parse* phase looked over every
input document before the *emit* phase ran. During the refactor this changed
and for each file the *emit* phase was running immediately after the *parse*
phase, when it should have been run only after all inputs had been through the
*parse* phase.
* Fixed a type in the ``LiterateMarkdownGenerator``: an extra '`/`' was being
inserted into the url for link targets.
* Refactored the overall process flow. Instead of ``JLPMain`` handling the
process, it now reads the command line options and defers to ``Processor`` to
handle the actual process. The ``Processor`` instance is responsible for
processing one batch of input files and holds all the state that is common to
this process.
* ``JLPBaseGenerator`` and generators based on it are now only responsible for
handling one file, generating output from a source AST. As a consequence
state that is common to the overall process is no longer stored in the
generator but is stored on the ``Processor`` instance, which is exposed to the
generators.
* Generators can now be instantiated directly (instead of having just a public
static method) and are no longer one-time use. Now the life of a generator is
expected to be the same as the life of the ``Processor``.
* Fixed inter-doc link behaviour.
* Created some data classes to replace the ad-hoc maps used to store state in
the generator (now in the ``Processor``)
* `relative-path-root` option added. This facilitates situations where the
current directory of the invocation context is different than the working
directory of the program. This is required to use `jlp` with tools like
*Nailgun*, which keeps a persistant `java` process running and proxies new
invocations to the existing process.
* Added CSS based on Docco (blatantly copied).
* Updated sample text to better fit the emerging usage patterns. Some of the
things I did to make it render nicely for the Literate output may cause
problems when we go to render API output. I will cross that bridge when I come
to it.
* Added parsing infrastructure to the Generator behaviour to allow a
pre-processing pass over the document. Current the LiterateMarkdownGenerator
is using this to compile a map of `@org` references.
* Tweaked the HTML output slightly.
* Added a layer over the PegDownProcessor in LiterateMarkdownGenerator to
capture and transform `jlp://` links into relative links.
Ideas:
* For literate output, format like Docco, tables like
Doc | Code
-----------|------------
| docblock | codeblock |
| docblock | codeblock |
| docblock | codeblock |
* For javadoc output, maybe create a running 'pure source' object containing
just the code lines. Then run an sup-parser for the language the code is
written in and build a seperate AST for the code. This code AST then gets
tagged onto the overall AST and is used in the generation phase for code
comprehension. Would still need a way to map doc blocks to code blocks. I
could probably use line numbers. In that case I would need to map the original
source line from the commented input to the 'pure source' while processing the
'pure source' and store the original line number in the code AST. That would
give me a reliable way to lookup the closest code structure to a doc block.
* The code AST would need to made of generic pieces if I want to have
language-agnostic generator code. What may be better is to allow the language
parser to create it's code AST however is wants and just have some pluggable
bit of the generator for each language. Would increase generator code
complexity though.
* Updated test data to include additional parsing edge cases.
* Updated `vbs_db_records.hrl` to use `@org` directives.
* Refactored Generator/Emitter dual-object phase concept into one object, the
Generator. The emitter ended up needing basically full visibility into the
generator anyways.
* Implemented `JLPBaseGenerator`, `MarkdownGenerator`, and
`TransparentGenerator`
* Modified the way the parser handles remaining lines to allow it to safely
handle empty lines.
* Added planning documentation regrding the process.
* Updated grammer.
* Refactored the test code a bit.
* Added sample input file from vbs-suite
* Refactored the AST node structure created by the parser.
For whatever reason, writing the parser in Groovy was causing weird errors
to occur when the parser or parse runner was created. Using a plain Java
source file fixed this.
