Markdown Discuss - Dec 2014 - markdown/commonmark document specification concept

For those who develop desktop markdown/commonmark editors, it would be
interesting to hear your comments about this

While people often treat `.md` files as normal text files. There are some
who might want to style their markdown file in a portable manner, so that
it looks more like a normal document regardless of where you are. ( A psudo
pdf in a sense)

While it is a good policy to keep `.md` files as simple as possible, due to
all the legacy software that reads the original markdown files. It may be a
good idea to create a new filetype that is aimed for for emulating aspects
of a normal word processor (styling your document). What would make this
filetype better than `.docx`, is that it perpetrates the markup from the
styling (via stylesheet) . ( e.g. if stylesheet is remote linked, then you
can update the styling for an entire organization easily . If embedded, the
content is still more readable than `.docx` files.)

In practical terms, it encourage users to type in markdown/commonmark, but
still allow for flexibility in distributing it as a visually attractive
office document.

### File Type Proposed ###

# .md ----> Is equiv to `.txt` so just uses the parser engine directly

# .mdoc -----> Parse the document's `metadata/config/style` first, then
send through the parser engine

# .mdocz ----> A file archive that contextually obtain configuration from
file structure and name of `.mdoc`,`.md`, and other support files in it.

### Description of each file type ###

# .mdoc

"no parse or show" sections are read first ( to take the place of
"link"
and "head" tags, etc...), before being passed to the parser.

This is aimed towards those who would like to write documents in a normal
text editor ( e.g. like a jekyll post)

    ---
    layout: post
    title: Blogging Like a Hacker
    ---

    content here

    --- style ---
    .style {color: blue}
    --------------

    --- style:post ---
    .style {color: red}
    ------------------


note: could have multiple selectable styles. By default the first style
without name is chosen. Named style can be selected depending on context
E.g. `style:print` print friendly style etc...

note2: If you reference a stylesheet, but do not embed it, it will look at
the environment for the nearest match. This is useful, in the context of a
company that wants every users to use the same stylesheet for internal
document. Of course, if you want to send it elsewhere in a consistent
manner, you do need to embed it.


# .mdocz

This is a document archive. This is more useful for those who use a
dedicated desktop editor.

Unlike other formats like EPUB, the settings is by context, rather than
configuration.

e.g.
>The zip file wouldn't contain any new syntax, but rather a collection of
existing formats (Markdown, CSS, png files, etc) linked together using
convention over configuration. For example, the print stylesheet could
always be called "print.css" and the appropriate meta data would be
automatically added to the generated HTML. - [quote="chrisalley, post:15,
topic:941"]

So when the document header says `style: post`

    ---
    style: post
    title: Blogging Like a Hacker
    ---

it knows to look for `post.css` in the folder CSS first. `layout:post`
would look at the layout folder first, before looking at the css folder. (
Much like Jekyll, we should consider support for `liquid template` system,
for flexible easy to maintain separation of content to layout).
> Authors might be able edit the text files within that container zip file
using their chosen editor (this would be application specific), so making
the files inside the container easy to read and write is important. We can
probably do better than using plain CSS too. Perhaps a preprocessor could
be used instead such as SASS (original, non-SCSS syntax) which uses
indention instead of curly braces/semicolons - closer to Markdown's
philosophy --- [quote="chrisalley, post:17, topic:941"]

Thus a typical structure of a book `.mdocz` is (This is just one possible
layout, it's contextual):

* index.mdoc
* /css/
* /layout/
* /images/
* /chapters/ <-- chapter documents here
* /bookmark/ <-- user notes here.

While a simple document like a resume, might only be a single .mdoc file
(easy to tell what to open first)  plus images scattered in root folder.


---

Original discussion thread:

http://talk.commonmark.org/t/commonmark-document-specification-for-desktop-readers/
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<https://pairlist6.pair.net/pipermail/markdown-discuss/attachments/20141215/88010966/attachment.html>

So what's the potential scope for each file type. Here is some to think of.

##`.md`

**scope: simple no frill container of text with simple markups**

* Simple documentation
* Simple Resumes
* Application specific files
 * Internal text (e.g. text in a game)
 * Wiki (backups of wikis)
 * Static Site Generators (like Jekyll)

##`.mdoc`:

**scope: relatively more complicated but more capable as a stand alone
single document with embedded/linked stylesheet**

* Stand alone resume
* Invoice
* Orders
* Forms
* email backup without attachments (or at least encoded in base 64)

## `.mdocz`:

**scope: A full document container ( a website in a box ), capable of being
displayed in many formats, e.g. pdf/html/mobile/etc...**

* Portafolio
* eBooks
* Articles with images
* Ezines
* Instruction Manuals
* Choose your adventure stories
* documented codes
 * E.g. code documentations in research, where python snippets are stored
in the /code/ folder
* manpage
* An email backup along with it's attachments and metadata

On Mon, Dec 15, 2014 at 11:09 AM, mofo syne <mofosyne at gmail.com>
wrote:
>
> For those who develop desktop markdown/commonmark editors, it would be
> interesting to hear your comments about this
>
> While people often treat `.md` files as normal text files. There are some
> who might want to style their markdown file in a portable manner, so that
> it looks more like a normal document regardless of where you are. ( A psudo
> pdf in a sense)
>
> While it is a good policy to keep `.md` files as simple as possible, due
> to all the legacy software that reads the original markdown files. It may
> be a good idea to create a new filetype that is aimed for for emulating
> aspects of a normal word processor (styling your document). What would make
> this filetype better than `.docx`, is that it perpetrates the markup from
> the styling (via stylesheet) . ( e.g. if stylesheet is remote linked, then
> you can update the styling for an entire organization easily . If embedded,
> the content is still more readable than `.docx` files.)
>
> In practical terms, it encourage users to type in markdown/commonmark, but
> still allow for flexibility in distributing it as a visually attractive
> office document.
>
> ### File Type Proposed ###
>
> # .md ----> Is equiv to `.txt` so just uses the parser engine directly
>
> # .mdoc -----> Parse the document's `metadata/config/style` first,
then
> send through the parser engine
>
> # .mdocz ----> A file archive that contextually obtain configuration
from
> file structure and name of `.mdoc`,`.md`, and other support files in it.
>
> ### Description of each file type ###
>
> # .mdoc
>
> "no parse or show" sections are read first ( to take the place of
"link"
> and "head" tags, etc...), before being passed to the parser.
>
> This is aimed towards those who would like to write documents in a normal
> text editor ( e.g. like a jekyll post)
>
>     ---
>     layout: post
>     title: Blogging Like a Hacker
>     ---
>
>     content here
>
>     --- style ---
>     .style {color: blue}
>     --------------
>
>     --- style:post ---
>     .style {color: red}
>     ------------------
>
>
> note: could have multiple selectable styles. By default the first style
> without name is chosen. Named style can be selected depending on context
> E.g. `style:print` print friendly style etc...
>
> note2: If you reference a stylesheet, but do not embed it, it will look at
> the environment for the nearest match. This is useful, in the context of a
> company that wants every users to use the same stylesheet for internal
> document. Of course, if you want to send it elsewhere in a consistent
> manner, you do need to embed it.
>
>
> # .mdocz
>
> This is a document archive. This is more useful for those who use a
> dedicated desktop editor.
>
> Unlike other formats like EPUB, the settings is by context, rather than
> configuration.
>
> e.g.
>
> >The zip file wouldn't contain any new syntax, but rather a
collection of
> existing formats (Markdown, CSS, png files, etc) linked together using
> convention over configuration. For example, the print stylesheet could
> always be called "print.css" and the appropriate meta data would
be
> automatically added to the generated HTML. - [quote="chrisalley,
post:15,
> topic:941"]
>
> So when the document header says `style: post`
>
>     ---
>     style: post
>     title: Blogging Like a Hacker
>     ---
>
> it knows to look for `post.css` in the folder CSS first. `layout:post`
> would look at the layout folder first, before looking at the css folder. (
> Much like Jekyll, we should consider support for `liquid template` system,
> for flexible easy to maintain separation of content to layout).
>
> > Authors might be able edit the text files within that container zip
file
> using their chosen editor (this would be application specific), so making
> the files inside the container easy to read and write is important. We can
> probably do better than using plain CSS too. Perhaps a preprocessor could
> be used instead such as SASS (original, non-SCSS syntax) which uses
> indention instead of curly braces/semicolons - closer to Markdown's
> philosophy --- [quote="chrisalley, post:17, topic:941"]
>
> Thus a typical structure of a book `.mdocz` is (This is just one possible
> layout, it's contextual):
>
> * index.mdoc
> * /css/
> * /layout/
> * /images/
> * /chapters/ <-- chapter documents here
> * /bookmark/ <-- user notes here.
>
> While a simple document like a resume, might only be a single .mdoc file
> (easy to tell what to open first)  plus images scattered in root folder.
>
>
> ---
>
> Original discussion thread:
>
>
>
http://talk.commonmark.org/t/commonmark-document-specification-for-desktop-readers/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<https://pairlist6.pair.net/pipermail/markdown-discuss/attachments/20141215/3ec52f6e/attachment.html>

I'm confused.  Are you creating software to handle these document 
formats, or are you looking for ideas for software that you want other 
people to create for you?

F-

On 12/14/14, 7:09 PM, mofo syne wrote:
> For those who develop desktop markdown/commonmark editors, it would be
> interesting to hear your comments about this
>
> While people often treat `.md` files as normal text files. There are
> some who might want to style their markdown file in a portable manner,
> so that it looks more like a normal document regardless of where you
> are. ( A psudo pdf in a sense)
>
> While it is a good policy to keep `.md` files as simple as possible, due
> to all the legacy software that reads the original markdown files. It
> may be a good idea to create a new filetype that is aimed for for
> emulating aspects of a normal word processor (styling your document).
> What would make this filetype better than `.docx`, is that it
> perpetrates the markup from the styling (via stylesheet) . ( e.g. if
> stylesheet is remote linked, then you can update the styling for an
> entire organization easily . If embedded, the content is still more
> readable than `.docx` files.)
>
> In practical terms, it encourage users to type in markdown/commonmark,
> but still allow for flexibility in distributing it as a visually
> attractive office document.
> ### File Type Proposed ###
>
> # .md ----> Is equiv to `.txt` so just uses the parser engine directly
>
> # .mdoc -----> Parse the document's `metadata/config/style` first,
then
> send through the parser engine
>
> # .mdocz ----> A file archive that contextually obtain configuration
> from file structure and name of `.mdoc`,`.md`, and other support files
> in it.
>
> ### Description of each file type ###
>
> # .mdoc
>
> "no parse or show" sections are read first ( to take the place of
"link"
> and "head" tags, etc...), before being passed to the parser.
>
> This is aimed towards those who would like to write documents in a
> normal text editor ( e.g. like a jekyll post)
>
>      ---
>      layout: post
>      title: Blogging Like a Hacker
>      ---
>      content here
>      --- style ---
>      .style {color: blue}
>      --------------
>
>      --- style:post ---
>      .style {color: red}
>      ------------------
>
>
> note: could have multiple selectable styles. By default the first style
> without name is chosen. Named style can be selected depending on context
> E.g. `style:print` print friendly style etc...
>
> note2: If you reference a stylesheet, but do not embed it, it will look
> at the environment for the nearest match. This is useful, in the context
> of a company that wants every users to use the same stylesheet for
> internal document. Of course, if you want to send it elsewhere in a
> consistent manner, you do need to embed it.
>
>
> # .mdocz
>
> This is a document archive. This is more useful for those who use a
> dedicated desktop editor.
>
> Unlike other formats like EPUB, the settings is by context, rather than
> configuration.
>
> e.g.
>
>  >The zip file wouldn't contain any new syntax, but rather a
collection
> of existing formats (Markdown, CSS, png files, etc) linked together
> using convention over configuration. For example, the print stylesheet
> could always be called "print.css" and the appropriate meta data
would
> be automatically added to the generated HTML. - [quote="chrisalley,
> post:15, topic:941"]
>
> So when the document header says `style: post`
>
>      ---
>      style: post
>      title: Blogging Like a Hacker
>      ---
>
> it knows to look for `post.css` in the folder CSS first. `layout:post`
> would look at the layout folder first, before looking at the css folder.
> ( Much like Jekyll, we should consider support for `liquid template`
> system, for flexible easy to maintain separation of content to layout).
>
>  > Authors might be able edit the text files within that container zip
> file using their chosen editor (this would be application specific), so
> making the files inside the container easy to read and write is
> important. We can probably do better than using plain CSS too. Perhaps a
> preprocessor could be used instead such as SASS (original, non-SCSS
> syntax) which uses indention instead of curly braces/semicolons - closer
> to Markdown's philosophy --- [quote="chrisalley, post:17,
topic:941"]
>
> Thus a typical structure of a book `.mdocz` is (This is just one
> possible layout, it's contextual):
>
> * index.mdoc
> * /css/
> * /layout/
> * /images/
> * /chapters/ <-- chapter documents here
> * /bookmark/ <-- user notes here.
>
> While a simple document like a resume, might only be a single .mdoc file
> (easy to tell what to open first)  plus images scattered in root folder.
>
>
> ---
>
> Original discussion thread:
>
>
http://talk.commonmark.org/t/commonmark-document-specification-for-desktop-readers/
>
>
> _______________________________________________
> Markdown-Discuss mailing list
> Markdown-Discuss at six.pairlist.net
> https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
>
-- 
Fletcher T. Penney
fletcher at fletcherpenney.net