{"thread":{"id":"23660","subject":"RFD: tables in documentation","startedAt":"2010-05-01T18:37:39Z","lastAt":"2010-05-25T11:59:19Z","messageCount":11,"participants":["Michael J Gruber","Jeff King","Will Palmer","Jonathan Nieder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"140703","messageId":"4BDC74F3.2020206@drmicha.warpmail.net","threadId":"23660","inReplyTo":null,"subject":"RFD: tables in documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-05-01T18:37:39Z","receivedAt":"2010-05-01T18:37:39Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Currently, all tables are formatted using indentation by spaces. This\nbreaks whenever AsciiDoc's parsing changes.\n\nInstead, I suggest to use AsciiDoc's table syntax which also produces\nproper tables in the HTML and man output. I formatted the first part of\nthe first table in git-read-tree(1) like that so that you can compare\neasily.\n\nI put it up at http://repo.or.cz/w/git/mjg.git/commit/table-example for\nyour viewing pleasure. I'd say it looks great even in links (but not in\nlynx). It also shows a problem of xmlto with multiple rowspans (the xml\nis correct, .1 apparently not), which could be circumvented easily by\nrepeating those cells.\n\nHTML:\nhttp://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.html\n\nMAN:\nhttp://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.1\n\nMAN converted to txt by man:\nhttp://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.1.txt\n\nMAN converted to HTML by man2html:\nhttp://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.1.html\n\nCheers,\nMichael\n"},{"id":"140730","messageId":"20100502050622.GF14776@coredump.intra.peff.net","threadId":"23660","inReplyTo":"4BDC74F3.2020206@drmicha.warpmail.net","subject":"Re: RFD: tables in documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-02T05:06:22Z","receivedAt":"2010-05-02T05:06:22Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:\n\n> Currently, all tables are formatted using indentation by spaces. This\n> breaks whenever AsciiDoc's parsing changes.\n> \n> Instead, I suggest to use AsciiDoc's table syntax which also produces\n> proper tables in the HTML and man output. I formatted the first part of\n> the first table in git-read-tree(1) like that so that you can compare\n> easily.\n\nConceptually I am in favor of semantic markup where possible. I find the\nresulting manpage a little harder to read, though. Is it possible for us\nto style it a bit more (e.g., such a simple table looks better, IMHO,\nwithout ascii-art borders).\n\n> I put it up at http://repo.or.cz/w/git/mjg.git/commit/table-example for\n> your viewing pleasure. I'd say it looks great even in links (but not in\n> lynx). It also shows a problem of xmlto with multiple rowspans (the xml\n> is correct, .1 apparently not), which could be circumvented easily by\n> repeating those cells.\n\nDid you put the source up anywhere? I didn't see it, but it would be\ninteresting to see how painful it is to write.\n\n-Peff\n"},{"id":"140767","messageId":"4BDD7E96.2050603@drmicha.warpmail.net","threadId":"23660","inReplyTo":"20100502050622.GF14776@coredump.intra.peff.net","subject":"Re: RFD: tables in documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-05-02T13:31:02Z","receivedAt":"2010-05-02T13:31:02Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jeff King venit, vidit, dixit 02.05.2010 07:06:\n> On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:\n> \n>> Currently, all tables are formatted using indentation by spaces. This\n>> breaks whenever AsciiDoc's parsing changes.\n>>\n>> Instead, I suggest to use AsciiDoc's table syntax which also produces\n>> proper tables in the HTML and man output. I formatted the first part of\n>> the first table in git-read-tree(1) like that so that you can compare\n>> easily.\n> \n> Conceptually I am in favor of semantic markup where possible. I find the\n> resulting manpage a little harder to read, though. Is it possible for us\n> to style it a bit more (e.g., such a simple table looks better, IMHO,\n> without ascii-art borders).\n\nI really don't know (about styling docbook's tables). We can easily\nswitch off the outer borders in AsciiDoc.\n\nThe docbook part of the toolchain makes me sick whenever I have to look\nat it. I really wish AsciiDoc could output roff straight away. I find it\nincredibly hard to find the relevant information for this part of the\ntoolchain since it involves xmlto as well as the style sheets. Also, at\nleast my version of xmlto/style sheets/whatever does not cope well with\nadjacent (or even non-adjacent multiple) rowspans, see below. Only the\nvger.k.o. outage kept me from posting without noticing this before...\n\n> \n>> I put it up at http://repo.or.cz/w/git/mjg.git/commit/table-example for\n>> your viewing pleasure. I'd say it looks great even in links (but not in\n>> lynx). It also shows a problem of xmlto with multiple rowspans (the xml\n>> is correct, .1 apparently not), which could be circumvented easily by\n>> repeating those cells.\n> \n> Did you put the source up anywhere? I didn't see it, but it would be\n> interesting to see how painful it is to write.\n\nhttp://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables\n\nTough guess, I know ;)\n\nMichael\n"},{"id":"140772","messageId":"1272811394.24767.7.camel@dreddbeard","threadId":"23660","inReplyTo":"4BDD7E96.2050603@drmicha.warpmail.net","subject":"Re: RFD: tables in documentation","fromName":"Will Palmer","fromEmail":"wmpalmer@gmail.com","sentAt":"2010-05-02T14:43:14Z","receivedAt":"2010-05-02T14:43:14Z","isPatch":false,"sender":{"key":"wmpalmer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/357044?v=4"},"body":"On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:\n> Jeff King venit, vidit, dixit 02.05.2010 07:06:\n> > On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:\n> > Did you put the source up anywhere? I didn't see it, but it would be\n> > interesting to see how painful it is to write.\n> \n> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables\n> \n> Tough guess, I know ;)\n> \n> Michael\n\nthat looks suspiciously like a format that's intended to be readable in\nboth plaintext and eventually-generated form. This is me speaking in\npure ignorance, but would something like:\n\n\n\n-- \n-- Will\n"},{"id":"140773","messageId":"1272811916.24767.16.camel@dreddbeard","threadId":"23660","inReplyTo":"1272811394.24767.7.camel@dreddbeard","subject":"Re: RFD: tables in documentation","fromName":"Will Palmer","fromEmail":"wmpalmer@gmail.com","sentAt":"2010-05-02T14:51:56Z","receivedAt":"2010-05-02T14:51:56Z","isPatch":false,"sender":{"key":"wmpalmer@gmail.com","avatar":"https://avatars.githubusercontent.com/u/357044?v=4"},"body":"sorry about that, apparently \"shift+enter\" means \"send\" to this thing...\n\nOn Sun, 2010-05-02 at 15:43 +0100, Will Palmer wrote:\n> On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:\n> > Jeff King venit, vidit, dixit 02.05.2010 07:06:\n> > > On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:\n> > > Did you put the source up anywhere? I didn't see it, but it would be\n> > > interesting to see how painful it is to write.\n> > \n> > http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables\n> > \n> > Tough guess, I know ;)\n> > \n> > Michael\n> \n\nthat looks suspiciously like a format that's intended to be readable in\nboth plaintext and eventually-generated form. This is me speaking in\npure ignorance, but would something like (though I assume not exactly):\n\n[cols=\"1,3*5,8\"]\n   |=====================\n   |\t\t   |I\t\t |H\t\t|M\t\t|Result\n   |     0\t   |nothing\t |nothing\t|nothing\t|(does not happen)\n   |     1\t   |nothing\t |nothing\t|exists\t\t|use M\n   |     2\t   |nothing\t |exists\t|nothing\t|remove path from index\n.2+|\t 3\t.2+|nothing   .2+|exists\t|exists, H == M |use M if \"initial checkout\", keep index otherwise\n\t\t\t\t\t\t exists, H != M |fail\n   |=====================\n\nwork as intended?\n\n\n-- \n-- Will\n"},{"id":"140774","messageId":"4BDD956F.5070800@drmicha.warpmail.net","threadId":"23660","inReplyTo":"1272811916.24767.16.camel@dreddbeard","subject":"Re: RFD: tables in documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-05-02T15:08:31Z","receivedAt":"2010-05-02T15:08:31Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Will Palmer venit, vidit, dixit 02.05.2010 16:51:\n> sorry about that, apparently \"shift+enter\" means \"send\" to this thing...\n> \n> On Sun, 2010-05-02 at 15:43 +0100, Will Palmer wrote:\n>> On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:\n>>> Jeff King venit, vidit, dixit 02.05.2010 07:06:\n>>>> On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:\n>>>> Did you put the source up anywhere? I didn't see it, but it would be\n>>>> interesting to see how painful it is to write.\n>>>\n>>> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables\n>>>\n>>> Tough guess, I know ;)\n>>>\n>>> Michael\n>>\n> \n> that looks suspiciously like a format that's intended to be readable in\n> both plaintext and eventually-generated form. This is me speaking in\n> pure ignorance, but would something like (though I assume not exactly):\n> \n> [cols=\"1,3*5,8\"]\n>    |=====================\n>    |\t\t   |I\t\t |H\t\t|M\t\t|Result\n>    |     0\t   |nothing\t |nothing\t|nothing\t|(does not happen)\n>    |     1\t   |nothing\t |nothing\t|exists\t\t|use M\n>    |     2\t   |nothing\t |exists\t|nothing\t|remove path from index\n> .2+|\t 3\t.2+|nothing   .2+|exists\t|exists, H == M |use M if \"initial checkout\", keep index otherwise\n> \t\t\t\t\t\t exists, H != M |fail\n>    |=====================\n> \n> work as intended?\n> \n\nUhm, how is that different from my patch (except for spaces which I\ndidn't bother with for this p-o-c)? [This is AsciiDoc - you know, do\nyou? ;)]\n\nJeff doesn't like the ascii art in the roff output (.1, as can be seen\nin the .1.txt file). It looks very \"strong\", just like the content.\n\nFurther experimentation (editing the xml) indicates that with my\ntoolchain, I can either shut off all borders (between cells as well as\nouter) or none. Why does working with the toolchain always frustrate me?\nIt's often a hindrance for improvements.\n\nSo, we could shut off all borders by adding an output dependent table\ndefinition in asciidoc.conf, copying current asciidoc's own and\nmodifying it for docbook-man output. Is it worth it? Maybe others like\nthe strong ascii borders...\n\nMichael\n"},{"id":"140779","messageId":"4BDD99F3.9000305@drmicha.warpmail.net","threadId":"23660","inReplyTo":"4BDD956F.5070800@drmicha.warpmail.net","subject":"Re: RFD: tables in documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-05-02T15:27:47Z","receivedAt":"2010-05-02T15:27:47Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Michael J Gruber venit, vidit, dixit 02.05.2010 17:08:\n> Will Palmer venit, vidit, dixit 02.05.2010 16:51:\n>> sorry about that, apparently \"shift+enter\" means \"send\" to this thing...\n>>\n>> On Sun, 2010-05-02 at 15:43 +0100, Will Palmer wrote:\n>>> On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:\n>>>> Jeff King venit, vidit, dixit 02.05.2010 07:06:\n>>>>> On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:\n>>>>> Did you put the source up anywhere? I didn't see it, but it would be\n>>>>> interesting to see how painful it is to write.\n>>>>\n>>>> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables\n>>>>\n>>>> Tough guess, I know ;)\n>>>>\n>>>> Michael\n>>>\n>>\n>> that looks suspiciously like a format that's intended to be readable in\n>> both plaintext and eventually-generated form. This is me speaking in\n>> pure ignorance, but would something like (though I assume not exactly):\n>>\n>> [cols=\"1,3*5,8\"]\n>>    |=====================\n>>    |\t\t   |I\t\t |H\t\t|M\t\t|Result\n>>    |     0\t   |nothing\t |nothing\t|nothing\t|(does not happen)\n>>    |     1\t   |nothing\t |nothing\t|exists\t\t|use M\n>>    |     2\t   |nothing\t |exists\t|nothing\t|remove path from index\n>> .2+|\t 3\t.2+|nothing   .2+|exists\t|exists, H == M |use M if \"initial checkout\", keep index otherwise\n>> \t\t\t\t\t\t exists, H != M |fail\n>>    |=====================\n>>\n>> work as intended?\n>>\n> \n> Uhm, how is that different from my patch (except for spaces which I\n> didn't bother with for this p-o-c)? [This is AsciiDoc - you know, do\n> you? ;)]\n> \n> Jeff doesn't like the ascii art in the roff output (.1, as can be seen\n> in the .1.txt file). It looks very \"strong\", just like the content.\n> \n> Further experimentation (editing the xml) indicates that with my\n> toolchain, I can either shut off all borders (between cells as well as\n> outer) or none. Why does working with the toolchain always frustrate me?\n> It's often a hindrance for improvements.\n> \n> So, we could shut off all borders by adding an output dependent table\n> definition in asciidoc.conf, copying current asciidoc's own and\n> modifying it for docbook-man output. Is it worth it? Maybe others like\n> the strong ascii borders...\n\nFor completeness, it results in this:\n\n     I                H         M               Result\n\n 0   nothing          nothing   nothing         (does not happen)\n\n 1   nothing          nothing   exists          use M\n\n 2   nothing          exists    nothing         remove path from index\n\n 3   nothing          exists    exists, H ==M   use M if \"initial\n                                                checkout\", keep index\n     exists, H != M             fail            otherwise\n\n[Same unealt rowspan issue, of course.]\nMichael\n"},{"id":"140786","messageId":"20100502175353.GA15521@progeny.tock","threadId":"23660","inReplyTo":"4BDD99F3.9000305@drmicha.warpmail.net","subject":"Re: RFD: tables in documentation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-02T17:53:54Z","receivedAt":"2010-05-02T17:53:54Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi Michael,\n\nMichael J Gruber wrote:\n> Michael J Gruber venit, vidit, dixit 02.05.2010 17:08:\n\n>> Further experimentation (editing the xml) indicates that with my\n>> toolchain, I can either shut off all borders (between cells as well as\n>> outer) or none.\n[...]\n> For completeness, it results in this:\n> \n>      I                H         M               Result\n> \n>  0   nothing          nothing   nothing         (does not happen)\n> \n>  1   nothing          nothing   exists          use M\n> \n>  2   nothing          exists    nothing         remove path from index\n> \n>  3   nothing          exists    exists, H ==M   use M if \"initial\n>                                                 checkout\", keep index\n>      exists, H != M             fail            otherwise\n> \n> [Same unealt rowspan issue, of course.]\n\nFor what it’s worth, except for the broken last row, I like this and\nfind it readable.  It is too bad there is no way to make it more\ncompact so more rows can fit on a screen or page.\n\nThe ideal, to delimit the header without appearing busy, would be to\njust have a thin horizontal rule separating the header from the\nremaining rows[1].  Vertical rules are almost never a good idea.\nMaybe frame=\"topbot\",grid=\"none\",options=\"header\" would be a good\napproximation.\n\nJonathan\n\n[1] Just my opinion.  I probably learned the aesthetic from Simon Fear.\nhttp://www.tex.ac.uk/cgi-bin/texfaq2html?label=destable\n"},{"id":"140789","messageId":"4BDDD14C.7040503@drmicha.warpmail.net","threadId":"23660","inReplyTo":"20100502175353.GA15521@progeny.tock","subject":"Re: RFD: tables in documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-05-02T19:23:56Z","receivedAt":"2010-05-02T19:23:56Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jonathan Nieder venit, vidit, dixit 02.05.2010 19:53:\n> Hi Michael,\n> \n> Michael J Gruber wrote:\n>> Michael J Gruber venit, vidit, dixit 02.05.2010 17:08:\n> \n>>> Further experimentation (editing the xml) indicates that with my\n>>> toolchain, I can either shut off all borders (between cells as well as\n>>> outer) or none.\n> [...]\n>> For completeness, it results in this:\n>>\n>>      I                H         M               Result\n>>\n>>  0   nothing          nothing   nothing         (does not happen)\n>>\n>>  1   nothing          nothing   exists          use M\n>>\n>>  2   nothing          exists    nothing         remove path from index\n>>\n>>  3   nothing          exists    exists, H ==M   use M if \"initial\n>>                                                 checkout\", keep index\n>>      exists, H != M             fail            otherwise\n>>\n>> [Same unealt rowspan issue, of course.]\n> \n> For what it’s worth, except for the broken last row, I like this and\n> find it readable.  It is too bad there is no way to make it more\n> compact so more rows can fit on a screen or page.\n> \n> The ideal, to delimit the header without appearing busy, would be to\n> just have a thin horizontal rule separating the header from the\n> remaining rows[1].  Vertical rules are almost never a good idea.\n> Maybe frame=\"topbot\",grid=\"none\",options=\"header\" would be a good\n> approximation.\n\nThat looks nice in HTML (and produces the correct xml), but\nunfortunately my docbook renders this as if I had frame=\"all\",grid=\"all\" :(\n\n> \n> Jonathan\n> \n> [1] Just my opinion.  I probably learned the aesthetic from Simon Fear.\n> http://www.tex.ac.uk/cgi-bin/texfaq2html?label=destable\n"},{"id":"142274","messageId":"20100525094621.GA984@coredump.intra.peff.net","threadId":"23660","inReplyTo":"4BDD7E96.2050603@drmicha.warpmail.net","subject":"Re: RFD: tables in documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-25T09:46:21Z","receivedAt":"2010-05-25T09:46:21Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"[This is an old message, but I'm going through some old threads on my\ntodo, and I owed you a response.]\n\nOn Sun, May 02, 2010 at 03:31:02PM +0200, Michael J Gruber wrote:\n\n> > Conceptually I am in favor of semantic markup where possible. I find the\n> > resulting manpage a little harder to read, though. Is it possible for us\n> > to style it a bit more (e.g., such a simple table looks better, IMHO,\n> > without ascii-art borders).\n> \n> I really don't know (about styling docbook's tables). We can easily\n> switch off the outer borders in AsciiDoc.\n\nI do think the border-less table that you presented later in the thread\nlooks good, modulo the row-span issue.\n\nAnd:\n\n> > Did you put the source up anywhere? I didn't see it, but it would be\n> > interesting to see how painful it is to write.\n> \n> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables\n\nI think the source remains pretty readable.\n\nSo assuming you can solve the row-span problem, I think it is a\npositive change.\n\n> The docbook part of the toolchain makes me sick whenever I have to look\n> at it. I really wish AsciiDoc could output roff straight away. I find it\n\nYes, I have also wished for that many times.\n\n-Peff\n"},{"id":"142278","messageId":"4BFBBB97.7010107@drmicha.warpmail.net","threadId":"23660","inReplyTo":"20100525094621.GA984@coredump.intra.peff.net","subject":"Re: RFD: tables in documentation","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-05-25T11:59:19Z","receivedAt":"2010-05-25T11:59:19Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jeff King venit, vidit, dixit 25.05.2010 11:46:\n> [This is an old message, but I'm going through some old threads on my\n> todo, and I owed you a response.]\n\nI've been revisiting this myself just the other day - did someone say\nconnecting minds?\n\n> \n> On Sun, May 02, 2010 at 03:31:02PM +0200, Michael J Gruber wrote:\n> \n>>> Conceptually I am in favor of semantic markup where possible. I find the\n>>> resulting manpage a little harder to read, though. Is it possible for us\n>>> to style it a bit more (e.g., such a simple table looks better, IMHO,\n>>> without ascii-art borders).\n>>\n>> I really don't know (about styling docbook's tables). We can easily\n>> switch off the outer borders in AsciiDoc.\n> \n> I do think the border-less table that you presented later in the thread\n> looks good, modulo the row-span issue.\n> \n> And:\n> \n>>> Did you put the source up anywhere? I didn't see it, but it would be\n>>> interesting to see how painful it is to write.\n>>\n>> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables\n> \n> I think the source remains pretty readable.\n> \n> So assuming you can solve the row-span problem, I think it is a\n> positive change.\n> \n>> The docbook part of the toolchain makes me sick whenever I have to look\n>> at it. I really wish AsciiDoc could output roff straight away. I find it\n> \n> Yes, I have also wished for that many times.\n> \n> -Peff\n\nUnfortunately, docbook still sucks. (I was hoping it would improve with\nFedora 13, although I knew it wouldn't.)\n\nI checked, again, that AsciiDoc produces correct docbook. But docbook\nhas a problem with adjacent rowspans, and also with frames and grids: As\nsoon as you specify any line element (say, \"frame=topbot\" or\n\"grid=columns\") docbook uses full frames and full grids. And I think\nhaving at least topbot would be helpful.\n\nI think we should just get rid off the nroff pages and view man pages in\nhtml through links or such... [I noticed that lynx doesn't cope with the\ntable, though.]\n\nAlternatively, I would set up a default configuration in asciidoc.conf\nwhich uses topbot for html and no lines whatsoever for docbook, and\ncircumvent adjacent rowspans. When/if docbook improves that workaround\ncan be changed in that single place.\n\nMichael\n"}]}