jlp/doc/issues/0007fn5.rst

`Include` Directive.
====================

Add a new directive: `include`. This directive allows the author to include
the contents of a URL inline in the documentation (can be an internal JLP
reference URL).

----

======== ===================
Created: 2011-12-29T11:23:52
======== ===================
Ground work for include directive, documentation. * Further documentation. * Decided to add an `include` directive. This will have reprecussions directly for the JLPPegParser, Directive, and LinkAnchor classes. Include needs more semantic meaning than we currently have in the process because the author needs some way to understand what is being included. If you include an org link defined earlier does it include the whole file? Just that doc block? Both may be the desired behavior in different situations, but I do not want to add a complex syntax for selecting, just name the link. Therefore there must be something about the link that determines how much in included. This means we need more information in LinkAnchor, some link `type` at a minimum. My current thought is: * @org defined links--this is the only type of LinkAnchor defined right now--always bring the whole DocBlock when they are included. * A new type of link anchor, call them source file links, bring the whole file when they are included. These types of anchors would be automatically created by the parser/generator (have not decided where it belongs yet). The whole SourceFile would need to be included, but we do not want to emit the normal header for the file so we may have to do somthing about the initial emit method. * Additional types of link anchors arise when we add language awareness to the process. In my current vision we will automatically add link anchors of different types when we parse code sections (function definition, class definition, etc.) and the include directive would bring in all the DocBlocks related to that code node. * Additional types of link anchors will arise when we implement the @api directive, we will think about that in the future. * Updated the JLPPegParser to recognise include directives. * Added the include directive to Directive.DirectiveTypes 2011-12-29 21:45:21 +00:00			`Include` Directive.
			`====================`

			Add a new directive: `include`. This directive allows the author to include
			`the contents of a URL inline in the documentation (can be an internal JLP`
			`reference URL).`

			`----`

			`======== ===================`
			`Created: 2011-12-29T11:23:52`
			`======== ===================`