<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>texinfo (third party plugin)</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="../../style.css" type="text/css" />
<link rel="stylesheet" href="../../local.css" type="text/css" />
</head>
<body>
<div class="page">
<div class="pageheader">
<div class="header">
<span>
<span class="parentlinks">
<a href="../../index.html">ikiwiki</a>/
<a href="../../plugins.html">plugins</a>/
<a href="../contrib.html">contrib</a>/
</span>
<span class="title">
texinfo (third party plugin)
</span>
</span>
</div>
</div>
<div id="pagebody">
<div id="content" role="main">
<p><span class="infobox">
Plugin: texinfo<br />
Author: <span class="createlink">tschwinge</span><br />
Included in ikiwiki: no<br />
Enabled by default: no<br />
Included in <a href="../goodstuff.html">goodstuff</a>: no<br />
Currently enabled: no<br />
</span></p>
<p><span class="createlink">I</span> started writing a plugin to render
<a href="http://www.gnu.org/software/texinfo/">GNU Texinfo</a>
inside the ikiwiki environment.</p>
<p>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.</p>
<p>The plugin is available at
<a href="http://git.savannah.gnu.org/cgit/hurd/web.git/plain/.library/IkiWiki/Plugin/texinfo.pm">http://git.savannah.gnu.org/cgit/hurd/web.git/plain/.library/IkiWiki/Plugin/texinfo.pm</a>.</p>
<p>It's very basic at the moment, but will be improved over time.</p>
<p>It also has not really been audited for any security issues.</p>
<h1>Issues</h1>
<h2>How can I use verbatiminclude?</h2>
<p>I only can post a file ...</p>
<h2>N-to-M Mapping of Input and Output Files</h2>
<p>Conventional ikiwiki <a href="../write.html#index6h3"><em>htmlize</em>ing</a> plugins
have a one-to-one mapping of input file and output file:
<code>some/where/page.mdwn</code> is rendered to <code>some/where/page.html</code>.
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:</p>
<ul>
<li>N Texinfo input files (a main <code>.texi</code> file,
several helper files (<code>fdl.texi</code>, <code>version.texi</code>, ...), and
additional text files which are included from the main <code>.texi</code>
file, e.g. <code>history.texi</code>, <code>libfoo.texi</code>, <code>libbar.texi</code>. --<span class="createlink">tschwinge</span></li>
</ul>
<blockquote>
<p>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. --<span class="createlink">Joey</span></p>
<blockquote>
<p><img src="../../smileys/question.png" alt="(?)" /> I'll see about a frob to get <code>makeinfo</code> provide me with a list of additional files
it used for rendering a given <code>.texi</code> file. --<span class="createlink">tschwinge</span></p>
</blockquote>
<p>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. --<span class="createlink">Joey</span></p>
<blockquote>
<p>Might it be an option to simply not render the pages that are already
being used as an <code>include</code> file for another <code>.texi</code> file?
But how to assemble that list before actually having rendered all <code>.texi</code> files?
One possibility might be to already render them at ikiwiki's <em>scanning</em> stage and
store the rendered HTML files into temporary directories, and then at ikiwiki's
<em>rendering</em> stage simply install the desired ones into the main tree and discard
the others. --<span class="createlink">tschwinge</span></p>
</blockquote>
</blockquote>
<ul>
<li>M Texinfo output files: the main <code>.texi</code> file (which <code>include</code>s
the other input files) is usually rendered into a (flat) hierarchy
of HTML files, one file per node, see the table on
<a href="http://www.gnu.org/software/texinfo/manual/texinfo/html_node/#Top">http://www.gnu.org/software/texinfo/manual/texinfo/html_node/#Top</a>
for an example. --<span class="createlink">tschwinge</span></li>
</ul>
<blockquote>
<p>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.</p>
<p>What hasn't been done though is a page creating more than one other <em>page</em>.
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. --<span class="createlink">Joey</span></p>
<blockquote>
<p>Currently I use <code>makeinfo --no-split</code> and render to stdout, so that I can
easily capture the output and stuff it into the appropriate ikiwiki data structure.
If we want to have multiple output files (which we'll eventually want to have,
to avoid having such large single-file outputs), we won't be able to
do this anymore.
<img src="../../smileys/question.png" alt="(?)" /> Then we'll need a way to find the main output file, which
will be the one to be copied into what ikiwiki expects to be the main output
of the rendered <code>.texi</code> file.
Perhaps (again) parse the <code>.texi</code> file for a <code>@setfilename</code> statement?
The other generated files will also have to
copied somewhere (preferably into a subdirectory named alike the main file
to avoid name space collisions; but need to take care of links between the files then)
and need to be registed within the ikiwiki system.
--<span class="createlink">tschwinge</span></p>
</blockquote>
</blockquote>
<p>There needs to be some logic to establish a mapping between the <em>N</em> input files
and the <em>M</em> output files.
(At least for web-editing via CGI this is needed: ikiwiki (currently) needs to be able
to deduce <em>one</em> input file from a given output file)
Easiest would be either to have <em>N = 1</em>
(plus perhaps some input files that are not meant to be editable, like <code>gpl.texi</code>)
or to have
<em>M = N</em> and have a <img src="../../smileys/question.png" alt="(?)" /> one-to-one mapping between <em>input file n</em> and <em>output file m</em>
(which is not possible in Texinfo's <code>makeinfo</code> at the moment).
--<span class="createlink">tschwinge</span></p>
<h2><code>makeinfo</code> Output</h2>
<p><code>makeinfo --html</code> is being used for rendering. It creates stand-alone
HTML files, while ikiwiki only needs the files' <code><body></code>s.</p>
<p><img src="../../smileys/question.png" alt="(?)" /> One possibility (which is what I'm doing at the moment) is to simply cut away
everythin until <code><body></code> is seen and after <code></body></code> has been seen. --<span class="createlink">tschwinge</span></p>
<h1>Bugs</h1>
<h2>Non-functional Texinfo Commands</h2>
<p>Those commands are know to not work currently:</p>
<ul>
<li><code>@printindex</code></li>
<li><code>@shortcontents</code></li>
<li><code>@contents</code></li>
</ul>
<p>This is due to <code>makeinfo</code> not providing this functionality if rendering to stdout.</p>
</div>
</div>
<div id="footer" class="pagefooter" role="contentinfo">
<div id="pageinfo">
<div class="pagedate">
Last edited <span class="date">Tue Feb 26 23:01:54 2019</span>
<!-- Created <span class="date">Tue Feb 26 23:01:54 2019</span> -->
</div>
</div>
<!-- from ikiwiki -->
</div>
</div>
</body>
</html>
