Convert docs pages with tables to textile format #843

wants to merge 4 commits into


None yet

6 participants

cobyism commented Mar 7, 2013

Yesterdaty @parkr and I discussed the way documentation pages in the new site containing tables currently require inline HTML for the tables (Markdown doesn’t have support for a table syntax). This isn’t as easy to maintain as it could be, so this PR will convert all docs pages containing tables over from .md to .textile, and switch to using Textile’s table syntax instead of inline HTML. It’s not ideal to have some docs pages written in markdown, and others in textile, but hopefully this should at least make it easier to maintain the documentation over time. Maybe downstream it would be worth also converting the rest of the docs (back) to textile so it’s all in a consistent format (I originally ported the docs to markdown when I pulled them out of the wiki—maybe that wasn’t a great idea?)

🚧 At the moment only the "structure" docs page is converted over, the rest will come 🔜. There’s probably also going to be some more CSS tweaking needed given the textile table output doesn’t contain some things the original styles expected like <thead>, and <tbody> elements, and <p> tags inside the table cells… All in good time 😁

parkr commented Mar 7, 2013

Thanks for your work on this 👍

cobyism commented Mar 7, 2013

No worries—glad to be able to help out! 😀

mattr- commented Mar 7, 2013

Perhaps I'm just an old curmudgeon, but I don't actually see anything wrong with the inline HTML in the markdown file. IMHO, it's actually easier to read and understand than Textile's table syntax. How is inline HTML not as easy to maintain? Perhaps somebody could explain it to me like I'm five? 😄

cobyism commented Mar 7, 2013

@mattr- There’s nothing really wrong with it per-se—in fact I originally converted the old wiki content from this textile format to markdown for the exact same reasons you just described. In terms of maintainability though, it’s a lot of extra markup to have to proof-read any time rows are added or removed from a table.

As an example, instead of having to add:

    <p>Description of the variable goes here.</p>

… it’s much less code to maintain to just write:

| @variable@ | Description of the variable goes here. |

It’s a pretty subjective call, but in my experience the more code there is to maintain, the more prone it is to errors—so I think using textile for the tables here is a net win. Also, if someone wants to contribute to the documentation but doesn’t know HTML, the textile table syntax is undoubtedly more approachable than inline HTML.

mattr- commented Mar 8, 2013

Thanks for the explanation! I'm convinced. 👍

mojombo commented Mar 9, 2013

Man, I hate Textile with a passion, and mixing docs formats feels really wrong to me. I don't really see enough benefit here to warrant the change. I actually like the HTML version better, in that it can be nicely formatted to fit within an 80px wide file. I'm 👎 on this one.

cobyism commented Mar 10, 2013

@mojombo I have no idea how you code in an 80px wide editor :trollface:, but I take your points (and the editor-wrap factor hadn’t occurred to me, since I mostly have soft-wrap turned on by default). I’mma close this, but leave the branch around in case @parkr wants to reopen with any counter-points 😄

@cobyism cobyism closed this Mar 10, 2013
parkr commented Mar 10, 2013

Ideal solution: write a spec for tables in Markdown. @mojombo, that'll be right up your alley 😉

ixti commented Mar 10, 2013

@cobyism I believe @mojombo mean 80 chars width. Usually such code is much easier to read. And most of the times lines with more than 80 chars contain "code smells".

I agree with @mojombo about properly "beautified" HTML tables. And would like to add that in fact diffs for such tables are easier to read as you can see diff of exact column that was changed, rather than full row.

@jekyllbot jekyllbot locked and limited conversation to collaborators Feb 27, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.