Add a descriptive README - tttml - converters for a simpler syntax than markdown
(HTM) git clone git://bitreich.org/tttml git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/tttml
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Tags
(DIR) README
---
(DIR) commit 988fa554a3a032a34b33f645453e1866fed54b39
(DIR) parent dfd29d4237158b9699334bbab6d22e4285e4a8a4
(HTM) Author: Josuah Demangeon <mail@josuah.net>
Date: Tue, 12 Jun 2018 23:07:21 +0200
Add a descriptive README
Diffstat:
M Makefile | 3 ---
M README | 169 +++++--------------------------
D a.out | 0
D a.out.core | 0
D t | 70 -------------------------------
5 files changed, 24 insertions(+), 218 deletions(-)
---
(DIR) diff --git a/Makefile b/Makefile
@@ -4,9 +4,6 @@ MAN5 = tttml.5
all:
-README: Makefile $(MAN1) $(MAN5)
- mandoc -T ascii $(MAN5) $(MAN1) | col -bx >$@
-
install:
mkdir -p $(PREFIX)/bin
cp $(BIN) $(PREFIX)/bin
(DIR) diff --git a/README b/README
@@ -1,158 +1,37 @@
-TTTML(5) File Formats Manual TTTML(5)
+Text To Text Markup Language (tttml)
+================================================================================
-NAME
- tttml - simpler markup syntax than markdown
+[git clone]: git://bitreich.org/tttml/
+git:/bitreich.org/tttml/
-SYNOPSIS
- file.md
+*tttml* is a simpler alternative to the markdown format. It is focused on
+maintaining well-formatted plain text documents that look good enough to be
+published without conversion.
-DESCRIPTION
- The tttml format is a very simple format for writiing text that look good
- enough to be published without conversion. It lacks the markdown
- recursive syntax (such as recursive lists anb quotes) which also remove
- markdown ambiguities. Each block of text is separated from anotherone by
- an empty line.
+This is an awk implementation and converts documents in two steps:
- paragraph
- Any non-special block of text:
+- the formatter fix the input if needed
- First paragraph of text.
+- the converters read this well-formatted input
- Second paragraph of text.
- title Block that ends by a line with only `=':
+tttml-fmt
+--------------------------------------------------------------------------------
- Title can therefore have multiple lines if required
- although it is not advised.
- ======================================================
+This is the formatter part. It takes a less rigid format (like markdown "lazy"
+forms) as input that may contain errors and fix them up as much as it is
+possible. It only print well formated output.
- heading
- Block that ends with a line with only `-':
- Heading can also have multiple lines
- ------------------------------------------------------
+tttml-gopher
+--------------------------------------------------------------------------------
- subheading
- Block with a single line with at least 3 leading `#' characters
- starting at subheading and going down the outline (subheading,
- subsubheading ...) every time an additionnal `#' is added:
+This is a converter. It takes a well-formatted document and convert it to the
+target format, in this case a gophermap: It converts the links and replace some
+ASCII by equivalent prettier UTF-8 symbols.
- ### Subheading
+It is easy to convert a gophermap into an HTML document. gophermap-html [1]
+does this.
- #### Subsubheading
-
- ##### Subsubsubheading
-
- tag Block that start with a tag line:
-
- *tagline with asterisks and a column*:
- Body of the tag block that can span over multiple
- lines like regular paragraphs.
-
- list Block that start with a dash:
-
- - List item. The following lines might not have
- leading space.
-
- - Note that multi-paragraph lists are not handled
-
- quote Block that has a leading `>' on every line:
-
- > Mail-style quoting. Note that nested quotes
- > are not handled.
-
- literal
- Block that has a leading tab on every line:
-
- Nothing gets interpreted in these blocks.
- They get printed as-is.
- They may contain extra tabs.
-
- link Block that start with a label line and eventual subsequent
- description lines:
-
- [label]: git://josuah.net/git/tttml
- git repository for the tttml set of tools
-
- [label2]: /url/without/description.txt
-
-SEE ALSO
- smu(1), simple markup - markdown like syntax:
- https://github.com/Gottox/smu
-
-AUTHORS
- Josuah Demangeon <mail@josuah.net>
-
-OpenBSD 6.3 April 19, 2018 OpenBSD 6.3
-
-------------------------------------------------------------------------------
-
-TTTML-FMT(1) General Commands Manual TTTML-FMT(1)
-
-NAME
- tttml-fmt - format/pretty-print a tttml file
-
-SYNOPSIS
- tttml-fmt [file...]
-
-DESCRIPTION
- The tttml-fmt utility reformat a tttml(5) and print valid format to
- stdout.
-
- Most markdown documents can be converted to tttml(5) with if they do not
- have recursive elents such as nested lists or nested quotes.
-
- o The paragraphs are being filled to 80 columns,
-
- o The empty lines are set as apropriate
-
- o The blocks merged together are separated, such as lists without
- separating blank spaces.
-
- o The title and heading horizontal lines are expanded to 80
- columns.
-
- o The tags with the tagline merged with the paragraph are separated
- on their own line.
-
-SEE ALSO
- tttml-gopher(1), smu(1), tttml(5), simple tttml - markdown like syntax:
- https://github.com/Gottox/smu
-
-AUTHORS
- Josuah Demangeon <mail@josuah.net>
-
-OpenBSD 6.3 April 19, 2018 OpenBSD 6.3
-
-------------------------------------------------------------------------------
-
-TTTML-GOPHER(1) General Commands Manual TTTML-GOPHER(1)
-
-NAME
- tttml-gopher - generate a gophermap from a tttml file
-
-SYNOPSIS
- tttml-gopher host port [file...]
-
-DESCRIPTION
- The tttml-gopher utility convert file to a gophermap format, simply by
- converting all link entries, converting tabs into spaces and printing the
- rest. host and port is used to set the host in links that do not have a
- host, such as /path/to/file.txt
-
- o All URI starting with a `/' and ending with a `/' are printed
- using the `1' entry type
-
- o All URI starting with a `/' and not ending with a `/' are printed
- using the `0'
-
- o All URI starting with `0', `1', `7', `8', `9', `a', `g', `h' or
- `I' followed by a `/' and all "gopher://" URI are printed using
- the corresponding entry type.
-
- o All other URI are printed using the `h' entry type
-
-AUTHORS
- Josuah Demangeon <mail@josuah.net>
-
-OpenBSD 6.3 April 19, 2018 OpenBSD 6.3
+[1]: /code/gophermap/
+gophermap
(DIR) diff --git a/a.out b/a.out
Binary files differ.
(DIR) diff --git a/a.out.core b/a.out.core
Binary files differ.
(DIR) diff --git a/t b/t
@@ -1,69 +0,0 @@
- TTTML(5) File Formats Manual TTTML(5)
- NAME tttml - simpler markup syntax than markdown SYNOPSIS file.md
- DESCRIPTION The tttml format is a very simple format for writiing text
- that look good enough to be published without conversion. It lacks the
- markdown recursive syntax (such as recursive lists anb quotes) which
- also remove markdown ambiguities. Each block of text is separated from
- anotherone by an empty line. paragraph Any
- non-special block of text: First paragraph of text.
- Second paragraph of text. title Block that ends by a line with only
- `=': Title can therefore have multiple lines if required
- although it is not advised.
- ====================================================== heading
- Block that ends with a line with only `-': Heading can also
- have multiple lines
- ------------------------------------------------------ subheading
- Block with a single line with at least 3 leading `#' characters
- starting at subheading and going down the outline (subheading,
- subsubheading ...) every time an additionnal `#' is added:
- ### Subheading #### Subsubheading #####
- Subsubsubheading tag Block that start with a tag line:
- *tagline with asterisks and a column*: Body of the tag block
- that can span over multiple lines like regular paragraphs.
- list Block that start with a dash: - List item. The
- following lines might not have leading space.
- - Note that multi-paragraph lists are not handled quote Block that
- has a leading `>' on every line: > Mail-style quoting. Note
- that nested quotes > are not handled. literal
- Block that has a leading tab on every line: Nothing
- gets interpreted in these blocks. They get printed
- as-is. They may contain extra tabs.
- link Block that start with a label line and eventual subsequent
- description lines: [label]: git://josuah.net/git/tttml
- git repository for the tttml set of tools [label2]:
- /url/without/description.txt SEE ALSO smu(1), simple markup - markdown
- like syntax: https://github.com/Gottox/smu AUTHORS Josuah
- Demangeon <mail@josuah.net> OpenBSD 6.3 April 19, 2018
- OpenBSD 6.3
- ------------------------------------------------------------------------------
- TTTML-FMT(1) General Commands Manual
- TTTML-FMT(1) NAME tttml-fmt - format/pretty-print a tttml file
- SYNOPSIS tttml-fmt [file...] DESCRIPTION The tttml-fmt utility
- reformat a tttml(5) and print valid format to stdout. Most
- markdown documents can be converted to tttml(5) with if they do not have
- recursive elents such as nested lists or nested quotes. o The
- paragraphs are being filled to 80 columns, o The empty lines are
- set as apropriate o The blocks merged together are separated,
- such as lists without separating blank spaces. o The
- title and heading horizontal lines are expanded to 80 columns.
- o The tags with the tagline merged with the paragraph are separated
- on their own line. SEE ALSO tttml-gopher(1), smu(1), tttml(5), simple
- tttml - markdown like syntax: https://github.com/Gottox/smu AUTHORS
- Josuah Demangeon <mail@josuah.net> OpenBSD 6.3 April 19,
- 2018 OpenBSD 6.3
- ------------------------------------------------------------------------------
- TTTML-GOPHER(1) General Commands Manual
- TTTML-GOPHER(1) NAME tttml-gopher - generate a gophermap from a tttml
- file SYNOPSIS tttml-gopher host port [file...] DESCRIPTION The
- tttml-gopher utility convert file to a gophermap format, simply by
- converting all link entries, converting tabs into spaces and printing the
- rest. host and port is used to set the host in links that do not have a
- host, such as /path/to/file.txt o All URI starting with a `/' and
- ending with a `/' are printed using the `1' entry type o
- All URI starting with a `/' and not ending with a `/' are printed
- using the `0' o All URI starting with `0', `1', `7', `8', `9',
- `a', `g', `h' or `I' followed by a `/' and all "gopher://" URI
- are printed using the corresponding entry type. o
- All other URI are printed using the `h' entry type AUTHORS Josuah
- Demangeon <mail@josuah.net> OpenBSD 6.3 April 19, 2018
- OpenBSD 6.3
-\ No newline at end of file