anon/contra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added man pages, corrected documentation

Browse Source
This commit is contained in:
anon
2023-11-15 15:34:40 +01:00
parent e362faf978
commit b9ab4ab13c
4 changed files with 129 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
documentation/cwheel.1 Normal file
View 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
View 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.

17
documentation/specification.md
View File

@ -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.

2
source/cli.cpp
View File

@ -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"