Merge branch 'master' into spalax

[git.ikiwiki.info.git] / doc / plugins / contrib / texinfo.mdwn

diff --git a/doc/plugins/contrib/texinfo.mdwn b/doc/plugins/contrib/texinfo.mdwn
index 6584648d64e8d5080e94c4d5f129cae982b41c9e..b6a6c4bf3b5c55f2d2e4ad6a8b3fede4249418c1 100644 (file)
--- a/doc/plugins/contrib/texinfo.mdwn
+++ b/doc/plugins/contrib/texinfo.mdwn
@@ -1,3 +1,5 @@
+[[!template id=plugin name=texinfo author="[[tschwinge]]"]]
+

 [[I|tschwinge]] started writing a plugin to render
 [GNU Texinfo](http://www.gnu.org/software/texinfo/)
 inside the ikiwiki environment.
 [[I|tschwinge]] started writing a plugin to render
 [GNU Texinfo](http://www.gnu.org/software/texinfo/)
 inside the ikiwiki environment.


@@ -6,13 +8,20 @@ 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.
 
 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 <http://www.schwinge.homeip.net/~thomas/tmp/texinfo.pm>.
+The plugin is available at
+<http://git.savannah.gnu.org/cgit/hurd/web.git/plain/.library/IkiWiki/Plugin/texinfo.pm>.

 
 It's very basic at the moment, but will be improved over time.
 
 
 It's very basic at the moment, but will be improved over time.
 

+It also has not really been audited for any security issues.
+

 
 # Issues
 
 
 # Issues
 

+## How can I use verbatiminclude?
+
+I only can post a file ...
+

 ## N-to-M Mapping of Input and Output Files
 
 Conventional ikiwiki [[*htmlize*ing|plugins/write#index6h3]] plugins
 ## N-to-M Mapping of Input and Output Files
 
 Conventional ikiwiki [[*htmlize*ing|plugins/write#index6h3]] plugins


@@ -25,14 +34,7 @@ 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`
 * 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
-  <http://www.gnu.org/software/texinfo/manual/texinfo/html_node/#Top>
-  for an example.
-
-How to teach this to ikiwiki?  --[[tschwinge]]
+  file, e.g. `history.texi`, `libfoo.texi`, `libbar.texi`.  --[[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
 
 > 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


@@ -46,7 +48,18 @@ How to teach this to ikiwiki?  --[[tschwinge]]
 > what the best way would be to avoid that. --[[Joey]]
 
 >> Might it be an option to simply not render the pages that are already
 > 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]]
+>> being used as an `include` file for another `.texi` file?
+>> But how to assemble that list before actually having rendered all `.texi` files?
+>> One possibility might be to already render them at ikiwiki's *scanning* stage and
+>> store the rendered HTML files into temporary directories, and then at ikiwiki's
+>> *rendering* stage simply install the desired ones into the main tree and discard
+>> the others.  --[[tschwinge]]
+
+* 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
+  <http://www.gnu.org/software/texinfo/manual/texinfo/html_node/#Top>
+  for an example.  --[[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).
 
 > 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).


@@ -60,6 +73,32 @@ How to teach this to ikiwiki?  --[[tschwinge]]
 > 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]]
 
 > 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]]
 

+>> Currently I use `makeinfo --no-split` 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.
+>> (?) 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 `.texi` file.
+>> Perhaps (again) parse the `.texi` file for a `@setfilename` 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.
+>> --[[tschwinge]]
+
+There needs to be some logic to establish a mapping between the *N* input files
+and the *M* output files.
+(At least for web-editing via CGI this is needed: ikiwiki (currently) needs to be able
+to deduce *one* input file from a given output file)
+Easiest would be either to have *N = 1*
+(plus perhaps some input files that are not meant to be editable, like `gpl.texi`)
+or to have
+*M = N* and have a (?) one-to-one mapping between *input file n* and *output file m*
+(which is not possible in Texinfo's `makeinfo` at the moment).
+--[[tschwinge]]
+

 
 ## `makeinfo` Output
 
 
 ## `makeinfo` Output
 


@@ -68,3 +107,16 @@ HTML files, while ikiwiki only needs the files' `<body>`s.
 
 (?) One possibility (which is what I'm doing at the moment) is to simply cut away
 everythin until `<body>` is seen and after `</body>` has been seen.  --[[tschwinge]]
 
 (?) One possibility (which is what I'm doing at the moment) is to simply cut away
 everythin until `<body>` is seen and after `</body>` has been seen.  --[[tschwinge]]

+
+
+# Bugs
+
+## Non-functional Texinfo Commands
+
+Those commands are know to not work currently:
+
+* `@printindex`
+* `@shortcontents`
+* `@contents`
+
+This is due to `makeinfo` not providing this functionality if rendering to stdout.