Markus Heiser <markus.heiser@xxxxxxxxxxx> writes: > We prefer list tables ... > > """Their advantage is that they are easy to create or modify and that the > diff of a modification is much more meaningful, because it is limited to > the modified content.""" > > By example: We have some very large tables with tons of rows and cols. > If you need to extend one column just by one character you have to edit > the whole table and the diff is not readable. > > It is not limited to big tables, e.g. if you patch a simple typo, > you might need touch content not related to your fix. > > At the end it is a trade of, what weights more, readability of the > plain text or readability of the patch / most often I would vote > for the latter. If the documentation is of any use of all there will be a lot more people reading it than will be reading patches making tweaks to it. Optimizing for patch readability seems like the wrong focus to me. The ext4 folks can decide what they like best in this specific case. But I think that the advice in favor of list tables is wrong in the general case; they are completely unreadable in their source form, and that goes against one of the key reasons we adopted RST in the first place. Somebody will surely try to add a list table to the wrong document someday and I'll get to live through another one of those nifty explosions - and I'll have neither reasons nor motivation to defend that policy. Thanks, jon
