X-Git-Url: https://scripts.mit.edu/gitweb/www/ikiwiki.git/blobdiff_plain/28a9eff5d58a7fbbfd8fc6e450471148511f8c0a..0bb61e51b7b5784a1ea6292c64fbe5b4a74b6a9e:/doc/plugins/contrib/texinfo.mdwn diff --git a/doc/plugins/contrib/texinfo.mdwn b/doc/plugins/contrib/texinfo.mdwn index 46aa7acf9..6584648d6 100644 --- a/doc/plugins/contrib/texinfo.mdwn +++ b/doc/plugins/contrib/texinfo.mdwn @@ -1,6 +1,70 @@ -[[I|tschwinge]] started writing a plugin to render [Texinfo](http://www.gnu.org/software/texinfo) +[[I|tschwinge]] started writing a plugin to render +[GNU Texinfo](http://www.gnu.org/software/texinfo/) inside the ikiwiki environment. +This plugin is not neccessarily meant to enable people to write arbitrary +wiki pages in the Texinfo format (even though that is possible, of course), +but rather to ease collaboration on existing Texinfo documents. + 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? --[[tschwinge]] + +> 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. --[[Joey]] + +>> (?) I'll see about a frob to get `makeinfo` provide me with a list of additional files +>> it used for rendering a given `.texi` file. --[[tschwinge]] + +> 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. --[[Joey]] + +>> Might it be an option to simply not render the pages that are already +>> being used as an `include` file for another `.texi` file? --[[tschwinge]] + +> 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]] + + +## `makeinfo` Output + +`makeinfo --html` is being used for rendering. It creates stand-alone +HTML files, while ikiwiki only needs the files' ``s. + +(?) One possibility (which is what I'm doing at the moment) is to simply cut away +everythin until `` is seen and after `` has been seen. --[[tschwinge]]