diff --git a/documentation/contra.1 b/documentation/contra.1 deleted file mode 100644 index 4933e59..0000000 --- a/documentation/contra.1 +++ /dev/null @@ -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 -Specify character to quote with. -Currently this is only relevant when CSML tag heads are translated: - - div (class: myclass) ->
-.br - A A -.br - | | -.br - quotes ------------+-------+ - -.IP \-o -Specify output file corresponding for the NEXT input. - -.IP \-i -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. diff --git a/documentation/contra.1.md b/documentation/contra.1.md new file mode 100644 index 0000000..3561bde --- /dev/null +++ b/documentation/contra.1.md @@ -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` *\* +: colon separeted list of option sets + +`S` *\* +: colon separeted list of special asymetric tags starters + +`i` *\* +: colon separeted list of tags which contents should be ignored + +`o` *\* +: specify output file name for the NEXT file + +`q` *\* +: use \ 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 + + + + + +
+
+ lorem ipsum +
+ + +``` + +and + +```C +// DOCTYPE HTML +html { + head { + } + body { + hr; + div (class: myclass) { + lorem ipsum + } + } +} +``` + +are different sides of the same coin. diff --git a/documentation/contra.5 b/documentation/contra.5 deleted file mode 100644 index 2bd1790..0000000 --- a/documentation/contra.5 +++ /dev/null @@ -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 [()] {} -.br -.B ; - -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. diff --git a/documentation/specification.md b/documentation/csml.5.md similarity index 79% rename from documentation/specification.md rename to documentation/csml.5.md index 4aa536c..faca226 100644 --- a/documentation/specification.md +++ b/documentation/csml.5.md @@ -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 ``` [()] {} ``` @@ -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: -``` - - - - - -
-
- lorem ipsum -
- - -``` -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.