source: project/wiki/eggref/5/markdown-svnwiki @ 37406

Last change on this file since 37406 was 37406, checked in by Kooda, 3 years ago

Document markdown-svnwiki for CHICKEN 5

File size: 5.3 KB
Line 
1
2== markdown-svnwiki
3[[toc:]]
4Converts Markdown to the svnwiki syntax used on the [[https://wiki.call-cc.org/edit-help|Chicken wiki]]. It uses [[https://wiki.call-cc.org/egg/lowdown|lowdown]] to transform Markdown into SXML before transforming it into svnwiki with [[https://wiki.call-cc.org/egg/sxml-transforms|sxml-transforms]]. Much credit goes to those two libraries, particularly lowdown which heavily influenced the code in markdown-svnwiki.
5
6markdown-svnwiki includes pre and post-processing phases for performing customizable transformations on the input and output. Some transformations, meant to make working with the Chicken wiki more convenient, are included by default. They are described in the section [[#special-syntax|Special Syntax]].
7
8
9=== Requirements
10* lowdown
11* sxml-transforms
12* miscmacros
13* srfi-37
14
15
16=== Usage
17markdown-svnwiki installs both a module and a command line utility. The command line utility is used as follows:
18
19    usage: markdown-svnwiki [-h | --help]
20                            [-o | --output-file NAME]
21                            [-e | --extension EXTENSION]
22                            [-t | --no-toc]
23                            [file]
24
25Convert the given Markdown file to CHICKEN's svnwiki syntax. If no file is given, stdin is read. If neither the output-file or extension arguments are given, the result is written to stdout. If the output-file argument is provided, the resulting svnwiki file is written to a file of that name. If the extension argument is given, the svnwiki file uses the same name as the input file, with the given extension.
26
27
28=== Documentation
29<procedure> (markdown->svnwiki input)</procedure>
30
31Convert the given {{input}} (may be a string or a port) into svnwiki, outputting to {{current-output-port}}.
32
33<parameter> pre-processing</parameter>
34
35An alist of functions that accept a string (the input to {{markdown->svnwiki}}) and should transform it in some way. By default contains one entry: {{code-blocks}}, for dealing with code blocks as described in Special Syntax.
36
37<parameter> post-processing</parameter>
38
39An alist of functions that accept a string (the pre-post-processed output from {{markdown->svnwiki}}) and should transform it in some way. By default contains: {{code-blocks}}, {{procedure}}, {{macro}}, {{read}}, {{parameter}}, {{record}}, {{string}}, {{class}}, {{method}}, {{constant}}, {{setter}}, {{syntax}}, and {{type}}, for dealing with code blocks and definition tags as described in Special Syntax.
40
41<parameter> toc</parameter>
42
43If true, inserts {{[[toc:]]}} after the first-level heading(s). Defaults to {{#t}}.
44
45
46==== Special syntax
47markdown-svnwiki supports the syntax highlighted code blocks that [[help.github.com/articles/github-flavored-markdown#syntax-highlighting|GitHub]], [[http://johnmacfarlane.net/pandoc/README.html#fenced-code-blocks|Pandoc]] and perhaps others support. It converts these blocks into the {{<enscript>}} tags that highlight with the given language. It does this using a pre and post-processing step, both named {{code-blocks}}. These code blocks take the following form:
48
49    ``` Scheme
50    code ...
51    ```
52
53Becomes:
54
55    <enscript highlight="scheme">
56    code ...
57    </enscript>
58
59Additionally, markdown-svnwiki supports a special syntax for adding the [[https://wiki.call-cc.org/edit-help#extensions-for-chicken-documentation|definition tags]] supported by the Chicken wiki. Single-line verbatim code blocks that begin with exactly four spaces followed by {{[definition-type]}} are given a {{<definition-type>}} tag. Only the tags supported by the Chicken wiki are supported. For example:
60
61        [procedure] (my-proc ...)
62
63Becomes:
64
65    <procedure>(my-proc ...)</procedure>
66
67
68=== Example
69This example can be compiled to make a command line program that accepts one argument - a Markdown file - and outputs a svnwiki file into the same directory. It shows the addition of of a pre-processing step - one that removes the first section called "Installation" (fairly indiscriminately, it stops at the first {{#}}).
70
71<enscript highlight="scheme">    
72(import
73  scheme
74  (chicken irregex)
75  (chicken process-context)
76  (chicken pathname)
77  markdown-svnwiki)
78
79(define file-name (cadr (argv)))
80(define output-name (pathname-replace-extension file-name "svnwiki"))
81
82(pre-processing
83 (cons
84  (cons 'remove-installation
85        (lambda (s)
86          (irregex-replace "## Installation[^#]*" s "")))
87  (pre-processing)))
88
89(call-with-output-file output-name
90  (lambda (output)
91    (call-with-input-file file-name
92      (lambda (input)
93        (current-output-port output)
94        (markdown->svnwiki input)))))
95</enscript>
96
97
98=== Version history
99
100==== Version 0.3.0
10117 March 2019
102
103* Ported to CHICKEN 5
104
105
106==== Version 0.2.0
10722 October 2014
108
109* Add command line utility
110
111
112==== Version 0.1.4
11311 May 2014
114
115* Add newlines after lists
116
117'''Version 0.1.3'''
118* Improve definition post-processing to allow multiple definitions to be placed with a single new line between them
119
120'''Version 0.1.2'''
121* Fix misplaced {{@}}s in emphasis, strong
122* Accept zero whitespace before language definition of code blocks
123
124'''Version 0.1.1'''
125* Fix erroneous newline in code blocks
126
127'''Version 0.1.0'''
128* Initial release
129
130
131=== Source repository
132Source available on [[https://github.com/AlexCharlton/markdown-svnwiki|GitHub]].
133
134Bug reports and patches welcome! Bugs can be reported via GitHub or to alex.n.charlton at gmail.
135
136
137=== Author
138Alex Charlton
139
140
141=== License
142BSD
143
Note: See TracBrowser for help on using the repository browser.