clean up the documentation situation
This commit is contained in:
anon
parent
e0b9e48f46
commit
3055ca71fa
@ -1,67 +0,0 @@
|
||||
.TH Contra 1 "November 2023" "Version 1.0" "Contra manual"
|
||||
|
||||
.SH NAME
|
||||
Contra \- Convert between CSML and XML/HTML.
|
||||
|
||||
.SH SYNOPSIS
|
||||
.B Contra
|
||||
([\fIOPTIONS\fR] \fIFILES\fR)+
|
||||
|
||||
.SH DESCRIPTION
|
||||
The Contra 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 Contra -c -q '$html:myTag' -o draft.html draft.csml
|
||||
|
||||
.SH SEE ALSO
|
||||
Contra(5).
|
||||
|
||||
.SH AUTHOR
|
||||
AGVXOV - agvxov@gmail.com.
|
||||
|
||||
.SH BUGS
|
||||
None known.
|
||||
78
documentation/contra.1.md
Normal file
78
documentation/contra.1.md
Normal file
@ -0,0 +1,78 @@
|
||||
# Contra 1 specification
|
||||
> The Contra 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.
|
||||
|
||||
## DESCRIPTION
|
||||
The *Contra* utility converts the "C Style Markup Language" to HTML/XML and vice versa.
|
||||
The primary aim is to maximize both editability and readability by dynamizing the markup representation.
|
||||
|
||||
## SYNOPSIS
|
||||
**Contra** [ *OPTIONS* ] *FILES*+
|
||||
|
||||
## OPTIONS
|
||||
|
||||
`c`
|
||||
: the input is to be force interpeted as CSML
|
||||
|
||||
`x`
|
||||
: the input is to be force interpeted as XML/HTML
|
||||
|
||||
`s` *\<string\>*
|
||||
: colon separeted list of option sets
|
||||
|
||||
`S` *\<string\>*
|
||||
: colon separeted list of special asymetric tags starters
|
||||
|
||||
`i` *\<string\>*
|
||||
: colon separeted list of tags which contents should be ignored
|
||||
|
||||
`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
|
||||
|
||||
## Translation
|
||||
Contra translates both ways in a single step,
|
||||
from top to bottom,
|
||||
perserving formatting.
|
||||
|
||||
## Example
|
||||
|
||||
```html
|
||||
<!-- DOCTYPE HTML -->
|
||||
<html>
|
||||
<head>
|
||||
</head>
|
||||
<body>
|
||||
<hr/>
|
||||
<div class='myclass'>
|
||||
lorem ipsum
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```C
|
||||
// DOCTYPE HTML
|
||||
html {
|
||||
head {
|
||||
}
|
||||
body {
|
||||
hr;
|
||||
div (class: myclass) {
|
||||
lorem ipsum
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
are different sides of the same coin.
|
||||
@ -1,57 +0,0 @@
|
||||
.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.
|
||||
@ -1,8 +1,4 @@
|
||||
# Contra specification
|
||||
> The Contra 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.
|
||||
|
||||
## C Style Markup Language
|
||||
# C Style Markup Language
|
||||
The C Style Markup Language -CSML for short- is a markup language
|
||||
that can be 1 to 1 translated into traditional markup languages such as XML or HTML.
|
||||
It's syntax -as the name suggests- is engineered to be similar to
|
||||
@ -12,13 +8,16 @@ It also happens to closely resemble Groovy's advanced templating language.
|
||||
|
||||
The rational behind it's creation is the realizations that:
|
||||
1. languages which have giant blocks (say thousands of lines) tend to be more readable if the block closing token explicitly states the block type being closed.
|
||||
|
||||
```ADA
|
||||
procedure exaple is
|
||||
begin
|
||||
;
|
||||
end
|
||||
```
|
||||
|
||||
2. languges with implicit block closing contain less redundant text and as a result, are easier to edit
|
||||
|
||||
```C
|
||||
void exaple() {
|
||||
;
|
||||
@ -38,9 +37,9 @@ then convert it back
|
||||
Or alternatively one could rapidly type out a webpage in CSML
|
||||
and seemlessly translate it in the end.
|
||||
|
||||
### Syntax
|
||||
## Syntax
|
||||
|
||||
#### Tags
|
||||
### Tags
|
||||
```
|
||||
<tag> [(<head>)] {<body>}
|
||||
```
|
||||
@ -77,7 +76,7 @@ or until the end of the _head_ (closing ')').
|
||||
The __body__ is everything enclosed by curly braces ("{}").
|
||||
It may contain more _tags_ or _comments_.
|
||||
|
||||
#### Escaping
|
||||
### 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:
|
||||
@ -93,7 +92,7 @@ List of escaped special characters:
|
||||
Note, that they are not requred to be always escaped,
|
||||
but are highly advised.
|
||||
|
||||
#### Comments
|
||||
### Comments
|
||||
CSML supports C99 comments,
|
||||
both single and multi line.
|
||||
That is:
|
||||
@ -104,46 +103,7 @@ That is:
|
||||
line*/
|
||||
```
|
||||
|
||||
#### Echoing
|
||||
### Echoing
|
||||
Anything not holding special meaning (tags, heads, comments) is considered regular text,
|
||||
which is significant.
|
||||
This includes whitespace too.
|
||||
|
||||
|
||||
## Translation
|
||||
Contra translates both ways in a single step,
|
||||
from top to bottom,
|
||||
perserving formatting.
|
||||
|
||||
Example:
|
||||
```
|
||||
<!-- DOCTYPE HTML -->
|
||||
<html>
|
||||
<head>
|
||||
</head>
|
||||
<body>
|
||||
<hr/>
|
||||
<div class='myclass'>
|
||||
lorem ipsum
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
and
|
||||
```
|
||||
// DOCTYPE HTML
|
||||
html {
|
||||
head {
|
||||
}
|
||||
body {
|
||||
hr;
|
||||
div (class: myclass) {
|
||||
lorem ipsum
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
are different sides of the same coin.
|
||||
|
||||
|
||||
See the man pages for further documentation.
|
||||
Loading…
x
Reference in New Issue
Block a user