Home → Suggestions →

Table proposal

• Edit

Rody Oldenhuis

05 Aug, 2014 02:42 PM

I intend to use MultiMarkdown in a documentation tool intended to replace MS Word/Excel as it is currently used by the company I work in.

As we write mostly technical documentation, representing data clearly and concisely is crucial. For many types of data, tables are often the only straightforward way to do this. So, in order to become a full replacement that can easily be adopted by even non-technical personnel, it is crucial that tables can be created almost effortlessly, and look great nonetheless.

Copy/pasting data between tools with on-the-fly conversion is of course one of the major challenges, but this is obviously not up to MMD. What I would like to discuss here is styling. Currently (if I've understood well), MMD4 supports only 1 fixed table style: "booktabs", in LaTeX terms. This style can be tweaked by including CSS files specific to

, but other than that, there is no control over the table style and including multiple styles in a single document will have to be done via separate files with their own metadata, and transclusion.

Also, in some cases it might be desirable to have a long caption (printed above/below the table) and a short caption (displayed in a \listoftables).

Therefore, I propose the following new syntax for tables:

<!-- short description = long description, style = booktabs --> 
{{ existing syntax for table body }}
[<long caption>]

<!-- aliases for the syntax above --> 
{{ existing syntax for table body }}
[][<long caption>][]

<!-- short description = long description, table type (entry in CSS, environment in LaTeX, etc.) = <style> --> 
{{ existing syntax for table body }}
[<style>][<long caption>]

<!-- short description = <short description>, table type (entry in CSS, environment in LaTeX, etc.) = <style> --> 
{{ existing syntax for table body }}
[<style>][<long caption>][<short description>]

Not sure on your standpoint regarding curly braces, but they could serve to disambiguate the arguments:

{{ existing syntax for table body }}
{<style>}[<long caption>]{<short description>}

The style argument would be converted to

<table class="style"> ... </table>

(HTML) or

\ifcsmacro{style}{}{%
    \begin{style} 
    .... (same as normal table's body) 
    \end{style}
\else{%
    % (table as it currently is)       
}
\fi

(LaTeX) and similar for the other formats.

Let me know what you think.

1. Support Staff 1 Posted by fletcher on 05 Aug, 2014 04:33 PM

   

   Thanks for writing in with this.

   The difficulty is that what one person needs for their specific use case is often very different from what another person needs.

   The exact numbers that I and others make up varies with each retelling, but the goal of MultiMarkdown is the do 80% of what 80% of people need. 80% of people don't need the complex tables that you do, and they certainly don't need them 80% of the time.

   Something like this would be appropriate for your own modifications to MMD, but I don't think it will make it into MMD per se -- it's too complex and for too narrow of a purpose.

   I understand that it might be exactly what you need, and that's fine -- go for it! But it doesn't fit the Markdown/MMD goal of a raw text document that does not "look" like it's filled with computer markup.

   If you want to create something that doesn't "break" in normal MMD, you could create a separate tool that takes your syntax for a table and creates separate files for each format (e.g. HTML, LaTeX, etc.) You would then use the transclusion feature to include the appropriate table format depending on the chosen output for the document. As far as MMD is concerned, you're simply using a hand-crafted HTML/LaTeX table inside a MMD document, which is perfectly fine. As long as other users had access to your table files, the document would "compile" just fine with stock MMD.

   • Edit

2. 2 Posted by Rody Oldenhuis on 06 Aug, 2014 09:20 AM

   

   You're a hard one to please :)

   Challenge accepted.

   I get your sentiment, but 80% of people are satisfied with regular markdown and do not need bibliographies, glossaries, etc. Yet, MMD exists.

   You recognized that there is a desire to not just include images, but to have some control over how they are displayed. To meet that desire, you implemented the possibility of including image attributes in a reference-style image.

   I contend that the same holds for tables. So, how about a similar syntax:

   <!-- inline style --> 
   {{ same table body }} 
   [<table caption>]
   

   as currently implemented in MMD4, or

   <!-- reference style --> 
   {{ same table body }} 
   [<id>]
   
   [id]: "<optional short description>": "<table caption>" attribute1 attribute2 ...
   

   Where attributes are HTML attributes added to the <table> header.

   The <id> is then also the label used for cross-references.

   What about that?

   • Edit

3. Support Staff 3 Posted by fletcher on 07 Aug, 2014 01:24 PM

   

   The question is not whether additional table features would be useful --
   clearly they would.

   The question is finding a syntax that is:

   1) Easy for humans to read and immediately understand

   2) That doesn't look like it's drowning in markup

   3) That is easy to manually create/type without a dedicated tool. (e.g.
   it's very easy to type MMD's current table syntax. It *looks* better
   with a proper tool, e.g. MultiMarkdown Composer, but it's easy enough
   with a dumb text editor.

   Looking at your examples, it's not immediately clear what this is
   supposed to mean. You'll have better luck with a real life example, not
   a description of the syntax.

   But even then, the offer to accept new table formats has gone unclaimed
   for years now. ;)

   • Edit

4. 4 Posted by Rody Oldenhuis on 11 Aug, 2014 06:50 AM

   

   My first proposal is bad, I can agree on that. Too proggy.

   The second proposal is well in line with the syntaxes of most of the other devices used by (multi)markdown. So, a concrete example. I propose to regard the existing table syntax as the "inline" form:

   This is a section. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed 
   do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad 
   minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea 
   commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse 
   cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non 
   proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
   
   |             |          Grouping           ||
   First Header  | Second Header | Third Header |
    ------------ | :-----------: | -----------: |
   Content       |          *Long Cell*        ||
   Content       |   **Cell**    |         Cell |
   
   New section   |     More      |         Data |
   And more      | With an escaped '\|'         ||  
   [Prototype table][tableLabel]
   
   This is another section, with a reference to [#tableLabel]. Lorem ipsum 
   dolor sit amet, et cetera.
   

   and extend it with a "reference" form:

   This is a section. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed 
   do eiusmod tempor incididunt ut labore et dolore magna aliqua. Et cetera.
   
   |             |          Grouping           ||
   First Header  | Second Header | Third Header |
    ------------ | :-----------: | -----------: |
   Content       |          *Long Cell*        ||
   Content       |   **Cell**    |         Cell |
   
   New section   |     More      |         Data |
   And more      | With an escaped '\|'         ||  
   ["Example of a table in MMD4. Note that the syntax is virtually the same 
   as PHP Markdown Extra."][myTable]
   
   This is another section, with a reference to [#myTable]. Lorem ipsum 
   dolor sit amet, et cetera.
   
   [myTable]: "MMD4 tables are awesome" class=colored_headers  width=85%
   

   This follows the same logic as images, which I think makes the most sense.

   Alternatively, you could follow "link" logic:

   This is a section. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed 
   do eiusmod tempor incididunt ut labore et dolore magna aliqua. Et cetera.
   
   |             |          Grouping           ||
   First Header  | Second Header | Third Header |
    ------------ | :-----------: | -----------: |
   Content       |          *Long Cell*        ||
   Content       |   **Cell**    |         Cell |
   
   New section   |     More      |         Data |
   And more      | With an escaped '\|'         ||  
   [myTable][]
   
   This is another section, with a reference to [#myTable]. Lorem ipsum 
   dolor sit amet, et cetera.
   
   [myTable]: "MMD4 tables are awesome": "Example of a table in MMD4. Note that 
   the syntax is virtually the same as PHP Markdown Extra." class=colored_headers  width=85%
   

   but IMHO, that's not as intuitive.

   So, yay or nay?

   • Edit

5. Support Staff 5 Posted by fletcher on 16 Aug, 2014 01:56 PM

   

   This is definitely better. I'll have to think about it.

   • Edit