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

clean up the documentation situation

Browse Source
This commit is contained in:
anon
2023-12-05 19:53:04 +01:00
parent e0b9e48f46
commit 3055ca71fa
4 changed files with 87 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
documentation/contra.1
View File

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

57
documentation/contra.5
View File

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

58
documentation/specification.md → documentation/csml.5.md
View File

@ -1,8 +1,4 @@
# Contra specification # C Style Markup Language
> 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
The C Style Markup Language -CSML for short- is a 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. 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 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: 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. 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 ```ADA
procedure exaple is procedure exaple is
begin begin
; ;
end end
``` ```
2. languges with implicit block closing contain less redundant text and as a result, are easier to edit 2. languges with implicit block closing contain less redundant text and as a result, are easier to edit
```C ```C
void exaple() { void exaple() {
; ;
@ -38,9 +37,9 @@ then convert it back
Or alternatively one could rapidly type out a webpage in CSML Or alternatively one could rapidly type out a webpage in CSML
and seemlessly translate it in the end. and seemlessly translate it in the end.
### Syntax ## Syntax
#### Tags ### Tags
``` ```
<tag> [(<head>)] {<body>} <tag> [(<head>)] {<body>}
``` ```
@ -77,7 +76,7 @@ or until the end of the _head_ (closing ')').
The __body__ is everything enclosed by curly braces ("{}"). The __body__ is everything enclosed by curly braces ("{}").
It may contain more _tags_ or _comments_. It may contain more _tags_ or _comments_.
#### Escaping ### Escaping
Any special character may be escaped by prepending it with a backslash ('\'). 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. This will prevent it from being parsed as a significant token to the syntax.
List of escaped special characters: List of escaped special characters:
@ -93,7 +92,7 @@ List of escaped special characters:
Note, that they are not requred to be always escaped, Note, that they are not requred to be always escaped,
but are highly advised. but are highly advised.
#### Comments ### Comments
CSML supports C99 comments, CSML supports C99 comments,
both single and multi line. both single and multi line.
That is: That is:
@ -104,46 +103,7 @@ That is:
line*/ line*/
``` ```
#### Echoing ### Echoing
Anything not holding special meaning (tags, heads, comments) is considered regular text, Anything not holding special meaning (tags, heads, comments) is considered regular text,
which is significant. which is significant.
This includes whitespace too. 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.