source: project/wiki/stream-wiki @ 8756

Last change on this file since 8756 was 8756, checked in by Ivan Raikov, 12 years ago

Added an entry for version 1.12.

File size: 10.3 KB
Line 
1[[tags:eggs streams eggsgpl]]
2
3[[toc:]]
4
5== Introduction
6
7Streams-based code for converting from the relatively
8standard and easy to type wiki format to many useful formats.
9
10It currently supports converting to the following formats:
11
12* HTML
13* LaTeX (useful for generating PDF files)
14* Text (useful for indexing contents without markup, for example for searching).
15
16We are working on implementing support for Texi.
17OpenDocumentFormat may come after.
18
19This egg provides the parsing functionality used by [[http://wiki.freaks-unidos.net/svnwiki|svnwiki]].
20Using this egg other content management systems could allow its users to upload and modify
21contents in wiki format and display it in many different formats.
22
23== Examples
24
25=== Converting from wiki format to HTML
26
27The following code receives input from current-input-port
28in wiki format and converts it to HTML written to
29current-output-port:
30
31<enscript highlight=scheme>(use stream-ext stream-wiki)
32
33(write-stream (wiki->html (port->stream (current-input-port))))</enscript>
34
35Note that the resulting page does not include the {{<html>}} and {{<body>}} tags
36(to make it easy to include it as part of a page with other stuff).
37
38=== Converting from wiki format to LaTeX
39
40The following code receives input from current-input-port
41in wiki format and converts it to LaTeX written to
42current-output-port. 
43
44<enscript highlight=scheme>(use stream-ext stream-wiki)
45
46(write-stream
47  (latex-page "english"
48              "article"
49              (wiki->latex (port->stream (current-input-port)))))</enscript>
50
51=== Returning the links in a file
52
53The following code reads information in wiki format from current-input-port
54and returns a stream with all the local links found.
55Note that links to absolute URLs are not considered local links and are thus not returned.
56Each entry in the stream has the form {{(dst name)}}, where
57{{dst}} is the target of the link and {{name}} the text shown in the link.
58
59<enscript highlight=scheme>(use stream-ext stream-wiki)
60
61(wiki-links (port->stream (current-input-port)))</enscript>
62
63=== Returning a list of tags in a file
64
65It is possible to include "tags" (in the sense of ''tagging'' files with ''categories'')
66in wiki pages as part of their contents.
67To do this, the page should include a stream of the form {{<nowiki>[[tags:tag0 ... tagn]]</nowiki>}}.
68This allows users of wiki systems to browse pages by categories (eg. list all pages
69having tag ''tag0'').
70
71The following code loads a file in wiki format from {{test.wiki}} and returns
72a stream of symbols, one for each tag found.
73
74<enscript highlight=scheme>(use stream-ext stream-wiki)
75
76(wiki-tags (port->stream (open-input-file "test.wiki")))</enscript>
77
78 
79== Authors
80
81This egg is made by [[http://azul.freaks-unidos.net/|Alejandro Forero Cuervo]] <azul@freaks-unidos.net>.
82
83== License
84
85The {{stream-wiki}} egg is available under the GNU General Public License.
86
87== Requirements
88
89This egg depends on the following:
90
91* [[srfi-40]]
92* [[stream-ext]]
93* [[html-stream]]
94* [[stream-parser]]
95* [[sandbox]]
96* [[posix]]
97* [[format-modular]]
98* [[stream-sections]]
99
100== Converting from wiki to HTML
101
102<enscript highlight=scheme>(wiki->html input [tail] [name] [open] [include] [linktypes] [make-header] [data-output-func] [check-exists?] [extensions] [url-adjust])</enscript>
103
104Converts from a simple wiki format (which is relatively
105standard nowadays) into HTML.
106
107{{input}} should be a stream of characters
108(built with the mechanisms provided by SRFI-40 or the stream-ext egg) with
109the contents in wiki-format; the
110function returns a stream of characters to
111be included as part of an HTML page.
112
113Note that the returned stream will be built dynamically as it is read
114(and so will the input stream be read).
115
116The following are the optional parameteres.
117Please be aware that they are bound to change in the future, hopefully as the interface is improved or generalized.
118
119; {{tail}}: Defaults to {{stream-null}}.  The stream of characters {{tail}} will be appended at the end of the parsing.
120; {{name}}: Defaults to {{""}}.  You should pass the name of the file currently being parsed.  The only reason it might be needed is in a {{TOC}} entry, passed to the procedure received as the {{open}} parameter.
121; {{open}}: Defaults to {{(constantly stream-null)}} (for security reasons; we won't allow the wiki contents to open files and include them unless the caller explicitly allows it).  This should be a procedure receiving a filename as a string and returning a stream of characters with its associated contents.  This is used for {{TOC}} entries.  If you trust your wiki contents, you could use {{(compose port->stream open-input-file)}} here.
122; {{include}}: Defaults to {{(lambda (name tail) tail)}}.  This function is used for files includes into the current file (with an {{include:file}} link).  It should return the contents that should be shown instead of the include directive, followed by the {{tail}}.  Currently they are not parsed by stream-wiki but included directly in the output, so if they are wiki contents you might want to call {{wiki->html}} on them before returning them.
123; linktypes : Defaults to {{(make-hash-table)}}.  A list of definitions for types of links, which you can build with {{load-linktypes}}.
124; make-header: Defaults to {{(make-html-header 1)}}.  Function to turn wiki headers into HTML.  TODO: Document better.
125; {{data-output-func}}: Defaults to {{(constantly stream-null)}}.  Use that for now.  This is used when an extension needs to generate a file, which currently only happens for the {{math}} tags.  TODO: Document better.
126; {{check-exists?}}: Defaults to {{(constantly #t)}}.  It is a procedure given a pathname.  It should check to see if the file exists in the wiki.  This is used to know if local links should be rendered in red (meaning the file doesn't exist) or in the regular color.
127; {{extensions}}: Defaults to {{(make-hash-table)}}.  Contains the list of extensions loaded that stream-wiki will use while rendering files.  They should be loaded with {{(load-extensions-from-file)}}.
128; {{url-adjust}}: Defaults to {{identity}}.  stream-wiki uses this for relative URLs in the wiki.  For example, if you want to turn all relative links into absolute links with some specific URL, use this function.  The procedure gets passed the link as a stream of characters and is expected to return a stream of characters itself.
129
130== Converting from wiki to LaTeX
131
132== Converting from wiki to Plain Text
133
134<enscript highlight=scheme>(wiki->text input [human-readable])</enscript>
135
136Remove all wiki markup from the stream of characters {{input}} and produce a corresponding stream of characters for its associated representation as a plain-text file.
137This is useful, for example, to register the file in a search database (see, for example, the [[estraier|estraier egg]]).
138
139{{human-readable}} specifies whether the resulting file will be optimized to be read by a human (eg. a user reading it over a text-only interface) or a computer (eg. an indexer using the [[estraier]] egg).
140
141== Analyzing wiki files
142
143=== Obtaining links
144
145<enscript highlight=scheme>(wiki-links input)</enscript>
146
147Return a stream with all local (not external) links in the stream of characters {{input}}.
148Each element in the stream is a stream of characters with the destination of the link.
149
150=== Obtaining sections
151
152=== Obtaining tags
153
154=== Obtaining a table of contents
155
156== Version history
157
158=== 1.12
159
160* Additional fixes to the texi code
161* Some tweaks to the latex-driver code
162
163=== 1.10
164
165* Imported texi code (from Ivan Raikov)
166* Some small tweaks and fixes, particularly a bug that would cause stream-wiki to take unearthly amounts of time to parse some strings.3
167
168=== 1.9.2
169
170* Fixed bug in the handling of lists.
171
172=== 1.9.1
173
174* Small bug fix by Kon.
175
176=== 1.9
177
178* Lots of bug fixes.
179* New handling of lists (see <http://listas.el-directorio.org/pipermail/svnwiki/2007-February/000035.html>).
180* Better handling of local links.  Links to unexistant local files are converted to a canonical form.
181* Extended the "driver" structure to support the "anchor" object.
182* Fixed the HTML generation for the anchors that used to wrap the headers.
183* Better handling for anchors.
184
185=== 1.8
186
187* Support for new types of extensions (code-break).
188* List of symbols that extensions can define is no longer hardcoded.
189* Allow the caller of {{wiki->html}} to pass the object that should be passed as an argument to extensions.
190* Allow tildes ({{~}}) in URLs.
191* Better handling of tags (as in HTML tags).
192* If multiple sections have the same name, use numbers to distinguish them in the anchors.
193* Never emit empty paragraphs ({{<p></p>}}).
194* Better support in the syntax for parameters to tags (as in HTML tags).
195* Register both internal and external links (previously {{wiki-links}} only reported internal links).
196* Allow the caller to specify for which external links we should use rel=nofollow for the HTML driver (by means of a callback function).
197* Better handling for definition lists.
198* Lots of new extensions and improvements to extensions.
199* Lots of bug fixes.
200
201=== Other releases
202
203TODO: Convert to the new format.
204
205; 1.7 : Support for new types of extensions.  This shouldn't be visible to stream-wiki users that don't use the extensions code advancedly (ie. only svnwiki should view this change).  In the future I will strip the extensions code to a separate egg, I think.
206; 1.6 : Added {{wiki->text}}, small fix in URL handling, adjust URLs in images (using {{check-exists?}} and {{url-adjust}}, don't strip HTML comments (since some users have reported they need to be able to include HTML comments in their wiki files, eg. for TOL).
207; 1.5 : Added {{url-adjust}} parameter for local/relative URLs.
208; 1.4 : Fixed a typo that was causing crashes during Texi/LaTeX output (again, the <=> string); made extensions see macros; more fixes in URL recognition; many fixes to the extension files.
209; 1.3 : Improvements in the recognition of URLs, the generation of TexVC math image files, add support for external extensions, preliminary menus and navigation for texi-driver (by Graham Fawcett), fixed typos that were causing problems with <blockquote> and LaTeX output and with the string <=>.
210; 1.2 : Improved the parsing of email addresses and URLs (which in some cases failed to recognized them as such).  Parse the result of evaluating linktypes as wiki format recursively (detecting infinite recursion and failing gracefully).
211; 1.1 : Lots of improvements, way too many to list here. :-/
212; 1.0 : First public release
Note: See TracBrowser for help on using the repository browser.