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 😁
swap structure.md to textile
convert table in structure page to textile format
adjust css for tables to work for textile-generated table output (no …
make min-height for articles tall enough for the lowest pages
the arrow provided by the `.current` class didn’t have a page on its
left to attach to, which made it look silly.
Thanks for your work on this 👍
No worries—glad to be able to help out! 😀
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? 😄
@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.
Thanks for the explanation! I'm convinced. 👍
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.
@mojombo I have no idea how you code in an 80px wide editor , 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 😄
Ideal solution: write a spec for tables in Markdown. @mojombo, that'll be right up your alley 😉
@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.