source: project/wiki/eggdoc-svnwiki @ 8503

Last change on this file since 8503 was 3487, checked in by svnwiki, 13 years ago

Changes applied for Zbigniew (67.167.53.235) through svnwiki:

eggdoc-svnwiki: Remove extra parens

File size: 5.7 KB
Line 
1[[tags:eggs]]
2
3This is version 0.1 of the '''eggdoc-svnwiki''' extension library for Chicken Scheme.
4
5[[toc:]]
6
7== Description
8
9
10Render eggdoc source to svnwiki syntax
11
12== Documentation
13
14
15eggdoc-svnwiki produces svnwiki output for Chicken eggs from eggdoc SXML source.
16
17=== Your eggdoc and you
18
19 '''procedure:''' (eggdoc->svnwiki DOC [STYLESHEET])
20
21Transform the SXML document {{DOC}} into svnwiki format using the optional SXSLT stylesheet {{STYLESHEET}}.  If not specified, the built-in stylesheet will be used, which is also accessible with {{eggdoc:make-svnwiki-stylesheet}}.
22
23
24 '''procedure:''' (eggdoc:make-svnwiki-stylesheet DOC)
25
26Returns the default SXSLT stylesheet, which transforms eggdoc input to svnwiki output.  This is a procedure because the stylesheet is built dynamically using the contents of the SXML document {{DOC}}.
27
28You can append to or modify this stylesheet and then pass it to {{eggdoc->svnwiki}}.
29
30 '''procedure:''' (eggdoc:make-defsig TAG SIG . [BODY])
31
32Use this procedure inside a stylesheet to generate a new signature tag, just like {{procedure}} or {{macro}}.  It expands to a {{(definition (signatures (signature ...)))}} expression.  For example,
33 (eggdoc->svnwiki doc `( ,@(eggdoc:make-svnwiki-stylesheet doc)
34                         (constant *macro* . ,eggdoc:make-defsig)
35                         (method   *macro* . ,eggdoc:make-defsig) ))
36
37will create new {{constant}} and {{method}} tags.
38
39=== Batch conversion
40
41Inside the egg under {{extras/}} I included some simple scripts to help with conversion of one or more eggdoc sources to svnwiki format.
42
43; {{eggdoc-svnwiki-shim.scm}} : Overrides standard eggdoc functions with eggdoc-svnwiki versions, so you do not have to modify the source.
44; {{eggdoc-html-to-svnwiki.sh}} : Converts standard eggdoc source to svnwiki plain text.
45
46== Limitations
47
48This extension has only been tested on a few eggs, unlike [[eggdoc-texinfo]] (which was tested on a hundred).  There are undoubtedly unresolved formatting issues that will be encountered.  Additionally, svnwiki has some peculiarities and bugs of its own.  Overall, however, the conversion quality is not too bad.
49
50* Nested lists are not handled
51* Nested definition lists won't render correctly (limitation of svnwiki)
52* <nowiki>#</nowiki>xxx at beginning of line or within <nowiki>&lt;</nowiki>td> is rendered as list (svnwiki bug)
53* Certain eggdocs may contain extraneous whitespace; if at beginning of line, may result in inadvertent PRE.
54* Escaping of command characters is not really bothered with.
55* Table attributes are ignored (limitation of svnwiki)
56* All other attributes are ignored except for {{href}}
57* Etc.
58
59== Examples
60
61For the direct, tedious approach, edit the source and change the {{eggdoc->html}} call to {{eggdoc->svnwiki}}, and {{(use eggdoc)}} to {{(use eggdoc-svnwiki)}}, then just call the eggdoc source script.
62
63To use the example script to convert existing eggdocs, unpack the egg and run the conversion script against the desired source:
64
65 ~/scheme/eggdoc-svnwiki$ mkdir output
66 ~/scheme/eggdoc-svnwiki$ sh extras/eggdoc-html-to-svnwiki.sh ~/eggdoc/eggdoc-objc.scm
67 ~/scheme/eggdoc-svnwiki$ cat output/eggdoc-objc.scm.svnwiki
68
69For batch conversion and addition to svnwiki I did something silly like
70
71 cd output
72 for i in *; do perl -e '$_ = $ARGV[0];
73   $f = $_; s/eggdoc-//; s/\.scm\.svnwiki//;
74   print "mv $f ~/scheme/chicken-eggs/wiki/$_\n";
75   print "(cd ~/scheme/chicken-eggs/wiki && svn add $_)\n" ' $i;
76 done
77
78resulting in script output which you can later direct to a shell:
79
80 mv eggdoc-args.scm.svnwiki ~/scheme/chicken-eggs/wiki/args
81 (cd ~/scheme/chicken-eggs/wiki && svn add args)
82 mv eggdoc-doctype.scm.svnwiki ~/scheme/chicken-eggs/wiki/doctype
83 (cd ~/scheme/chicken-eggs/wiki && svn add doctype)
84 mv eggdoc-eggdoc.scm.svnwiki ~/scheme/chicken-eggs/wiki/eggdoc
85 (cd ~/scheme/chicken-eggs/wiki && svn add eggdoc)
86 mv eggdoc-hostinfo.scm.svnwiki ~/scheme/chicken-eggs/wiki/hostinfo
87 (cd ~/scheme/chicken-eggs/wiki && svn add hostinfo)
88 mv eggdoc-sxml-tools.scm.svnwiki ~/scheme/chicken-eggs/wiki/sxml-tools
89 (cd ~/scheme/chicken-eggs/wiki && svn add sxml-tools)
90
91Ugly but effective.
92
93== About this egg
94
95=== Author
96
97[[http://3e8.org/zb|Zbigniew]]
98=== Version history
99
100; 0.1 : Initial release
101
102=== Requirements
103
104
105{{[[sxml-transforms]]}}, {{[[sxml-tools]]}}
106
107=== License
108
109 Copyright (c) 2007 Jim "Zb" Ursetto.  All rights reserved.
110 
111 Redistribution and use in source and binary forms, with or without
112 modification, are permitted provided that the following conditions are met:
113 
114   Redistributions of source code must retain the above copyright notice,
115   this list of conditions and the following disclaimer. Redistributions in
116   binary form must reproduce the above copyright notice, this list of
117   conditions and the following disclaimer in the documentation and/or
118   other materials provided with the distribution. Neither the name of the
119   author nor the names of its contributors may be used to endorse or
120   promote products derived from this software without specific prior
121   written permission.
122 
123 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
124 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
125 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
126 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
127 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
128 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
129 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
130 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
131 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
132 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
133 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
134
Note: See TracBrowser for help on using the repository browser.