added man pages, corrected documentation
This commit is contained in:
anon
parent
e362faf978
commit
b9ab4ab13c
67
documentation/cwheel.1
Normal file
67
documentation/cwheel.1
Normal file
@ -0,0 +1,67 @@
|
||||
.TH CWheel 1 "November 2023" "Version 1.0" "CWheel manual"
|
||||
|
||||
.SH NAME
|
||||
cwheel \- Convert between CSML and XML/HTML.
|
||||
|
||||
.SH SYNOPSIS
|
||||
.B cwheel
|
||||
([\fIOPTIONS\fR] \fIFILES\fR)+
|
||||
|
||||
.SH DESCRIPTION
|
||||
The CWheel utility converts so called the "C Style Markup Language" to HTML/XML and back.
|
||||
The primary aim is to maximize both editability and readability by dynamizing the markup representation.
|
||||
|
||||
.SH OPTIONS
|
||||
.IP \-h, \-\-help
|
||||
Print help and quit.
|
||||
|
||||
.IP \-v, \-\-version
|
||||
Print version and quit.
|
||||
|
||||
.IP \-c
|
||||
Force the interpretation of input as CSML.
|
||||
This applies to ALL input files following the option.
|
||||
|
||||
.IP \-x
|
||||
Force the interpretation of input as conventional markup.
|
||||
This applies to ALL input files following the option.
|
||||
|
||||
.IP \-q <char>
|
||||
Specify character to quote with.
|
||||
Currently this is only relevant when CSML tag heads are translated:
|
||||
|
||||
div (class: myclass) -> <div class='myclass'>
|
||||
.br
|
||||
A A
|
||||
.br
|
||||
| |
|
||||
.br
|
||||
quotes ------------+-------+
|
||||
|
||||
.IP \-o <file>
|
||||
Specify output file corresponding for the NEXT input.
|
||||
|
||||
.IP \-i <string>
|
||||
Specify a whitespace sensitive, colon separated list of tags's content should be ignored.
|
||||
For example, if the contents of a "script" tag were to be parsed
|
||||
it could completelly break the tag stack.
|
||||
This option is for avoiding such situations.
|
||||
|
||||
If a list member's name start with a '$' it's interpreted as a "set".
|
||||
Sets are predefined lists.
|
||||
|
||||
The currently available lists are:
|
||||
|
||||
$html - style:script
|
||||
|
||||
.SH EXAMPLES
|
||||
.B cwheel -c -q '$html:myTag' -o draft.html draft.csml
|
||||
|
||||
.SH SEE ALSO
|
||||
cwheel(5).
|
||||
|
||||
.SH AUTHOR
|
||||
AGVXOV - agvxov@gmail.com.
|
||||
|
||||
.SH BUGS
|
||||
None known.
|
||||
57
documentation/cwheel.5
Normal file
57
documentation/cwheel.5
Normal file
@ -0,0 +1,57 @@
|
||||
.TH CSML 5 "November 2023" "Version 1.0" "CSML Manual"
|
||||
|
||||
.SH NAME
|
||||
CSML \- C Style Markup Language Documentation
|
||||
|
||||
.SH DESCRIPTION
|
||||
The C Style Markup Language (CSML) is a markup language designed for 1 to 1 translation into traditional markup languages such as XML or HTML. Its syntax is engineered to be similar to the C programming language and resembles Groovy's advanced templating language.
|
||||
|
||||
CSML is intended to be a temporary representation of other markup languages during their editing. Developers can open a file in another markup language, convert it to CSML, make updates, and then convert it back without losing any data.
|
||||
|
||||
.SH SYNTAX
|
||||
.SS Tags
|
||||
.br
|
||||
.B <tag> [(<head>)] {<body>}
|
||||
.br
|
||||
.B <tag>;
|
||||
|
||||
Example:
|
||||
.br
|
||||
.B textarea (readonly) { lorem ipsum }
|
||||
.br
|
||||
.B br;
|
||||
|
||||
The last identifier, defined by the regular expression: [A-z][A-z0-9]*, before an (optional) head, body, or semicolon is considered to be a tag. CSML does not enforce any (sub)set of words to be "valid". Each tag is pushed into a stack and later popped by the end of a body being found.
|
||||
|
||||
If the tag is followed by a semicolon (';'), it's a self-closing tag.
|
||||
|
||||
The head holds attributes. A missing head signals that there are no attributes to be translated. Any text may be a valid attribute. Attributes can be given values by placing a colon (':') after them.
|
||||
|
||||
The value is parsed until the first non-escaped comma (',') or until the end of the head (closing ')').
|
||||
|
||||
The body is everything enclosed by curly braces ("{}"). It may contain more tags or comments.
|
||||
|
||||
.SS Escaping
|
||||
Any special character may be escaped by prepending it with a backslash ('\\'). This will prevent it from being parsed as a significant token to the syntax.
|
||||
List of escaped special characters:
|
||||
+ \\(
|
||||
+ \\)
|
||||
+ \\{
|
||||
+ \\}
|
||||
+ \\,
|
||||
+ \\:
|
||||
+ \\;
|
||||
|
||||
Note, that they are not required to be always escaped, but are highly advised.
|
||||
|
||||
.SS Comments
|
||||
CSML supports C99 comments, both single and multi-line.
|
||||
|
||||
Example:
|
||||
.br
|
||||
.B //single line
|
||||
.br
|
||||
.B /*multi-line*/
|
||||
|
||||
.SS Echoing
|
||||
Anything not holding special meaning (tags, heads, comments) is considered regular text, which is significant. This includes whitespace too.
|
||||
@ -27,7 +27,7 @@ void exaple() {
|
||||
|
||||
So,
|
||||
CSML is indended to be a temporary representation of other markup languages
|
||||
for the duration of their céltudatos^HU editing.
|
||||
for the duration of their directed editing.
|
||||
In practice,
|
||||
the developer would open a -say HTML- file,
|
||||
find the relevant section to modify,
|
||||
@ -71,7 +71,7 @@ A missing _head_ signals that there are no attributes to be translated.
|
||||
Any text may be a valid __attribute__.
|
||||
_Attributes_ can be given _values_ by placing a colon (':') after them.
|
||||
|
||||
The __value__ is parsed until the first non-escaped vessző^HU (',')
|
||||
The __value__ is parsed until the first non-escaped comma (',')
|
||||
or until the end of the _head_ (closing ')').
|
||||
|
||||
The __body__ is everything enclosed by curly braces ("{}").
|
||||
@ -92,7 +92,7 @@ Note, that they are not requred to be always escaped,
|
||||
but are highly advised.
|
||||
|
||||
#### Comments
|
||||
CSML supports C99 style comments,
|
||||
CSML supports C99 comments,
|
||||
both single and multi line.
|
||||
That is:
|
||||
```C
|
||||
@ -144,13 +144,4 @@ html {
|
||||
are different sides of the same coin.
|
||||
|
||||
|
||||
## Cli
|
||||
```
|
||||
cwheel [options] <file>+
|
||||
-c : the input is to be force interpeted as CSML
|
||||
-x : the input is to be force interpeted as XML/HTML
|
||||
-o <file> : specify output file name for the NEXT file
|
||||
-q <char> : use <char> for quoting (default: "'")
|
||||
-v : print version and quit
|
||||
-h : print help and quit
|
||||
```
|
||||
See the man pages for further documentation.
|
||||
|
||||
@ -11,7 +11,7 @@ const char * const help_message =
|
||||
"cwheel [options] <file>+\n"
|
||||
" -c : the input is to be force interpeted as CSML\n"
|
||||
" -x : the input is to be force interpeted as XML/HTML\n"
|
||||
" -i <string> : coma separeted list of tags which contents should be ignored\n"
|
||||
" -i <string> : colon separeted list of tags which contents should be ignored\n"
|
||||
" -o <file> : specify output file name for the NEXT file\n"
|
||||
" -q <char> : use <char> for quoting (default: \"'\")\n"
|
||||
" -v : print version and quit\n"
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user