X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/28a9eff5d58a7fbbfd8fc6e450471148511f8c0a..3f85a480098641fd07e4dec8693d025634ba8017:/doc/plugins/contrib/texinfo.mdwn diff --git a/doc/plugins/contrib/texinfo.mdwn b/doc/plugins/contrib/texinfo.mdwn index 46aa7acf9..cb2bf038c 100644 --- a/doc/plugins/contrib/texinfo.mdwn +++ b/doc/plugins/contrib/texinfo.mdwn @@ -1,6 +1,59 @@ -[[I|tschwinge]] started writing a plugin to render [Texinfo](http://www.gnu.org/software/texinfo) +[[I|tschwinge]] started writing a plugin to render [Texinfo](http://www.gnu.org/software/texinfo/) inside the ikiwiki environment. The plugin is available at . It's very basic at the moment, but will be improved over time. + + +# Issues + +## N-to-M Mapping of Input and Output Files + +Conventional ikiwiki [[*htmlize*ing|plugins/write#index6h3]] plugins +have a one-to-one mapping of input file and output file: +`some/where/page.mdwn` is rendered to `some/where/page.html`. +This can also be achieved for Texinfo files, but is somewhat +unusual there, when rendering them to HTML. In general, there +is a N-to-M mapping: + +* N Texinfo input files (a main `.texi` file, + several helper files (`fdl.texi`, `version.texi`, ...), and + additional text files which are included from the main `.texi` + file, e.g. `history.texi`, `libfoo.texi`, `libbar.texi`. +* M Texinfo output files: the main `.texi` file (which `include`s + the other input files) is usually rendered into a (flat) hierarchy + of HTML files, one file per node, see the table on + + for an example. + +How to teach this to ikiwiki? + +> As far as multiple input files, you'd need to use add_depends() +> to let ikiwiki know that a change to any of those files should cause a +> rebuild of the "main" file. I guess you'd also have to somehow deal with +> it wanting to render pages for each of the helper files. Not quite sure +> what the best way would be to avoid that. +> +> Ikiwiki is perfectly happy with a page creating other files (see eg, the +> img and teximg plugins, as well as the inline plugin's rss generation). +> The will_render() function supports that. +> +> What hasn't been done though is a page creating more than one other _page_. +> Perhaps you could call IkiWiki::genpage by hand for each additional page. +> You might also want to manipulate each data structure that tracks info about +> pages, adding the additional pages to them, so that they're first class +> pages that work as pages everywhere in ikiwiki (ie, can be inlined, +> appear in a site map, be linked to, etc). Not sure how to do that, +> and perhaps you could get away without doing it actually. --[[Joey]] + +## Copyright and Licensing Snippets + +ikiwiki (obviously) doesn't understand (parse) the copyright and licensing +statements which are included in `.texi` files. + + +## `makeinfo` Output + +`makeinfo --html` is being used for rendering. It creates stand-alone +HTML files, while ikiwiki only needs the files' ``s.