Junio C Hamano <gitster@xxxxxxxxx> writes: > So it looks as if the only place that needs the ugly '+' > continuation marker is between the first and the second > paragraph. And it also appears that the manpage backend does > not pay attention to the paragraph break there (HTML backend > places a <br /> before "With <em>--pretty</em>"). > > Is it just me, or the more we look at it, everybody doubts if > AsciiDoc was such a good choice? I don't think you should overgeneralize right now. Every input format will need some massaging, possibly resulting in ugliness. AsciiDoc _can_ be converted to plain text without markup. Whether this is worth doing depends on just how many people actually access the .txt files, and how much they are disturbed by things that are just there for leading AsciiDoc on the right path. One can also cater for particular patterns in the configuration files rather than in the source files. However, there are some things which can't be ironed out: adding useful indexing information will certainly disturb perusing the .txt files as text. And I consider good indexing important. There also is the problem that AsciiDoc works with a format _chain_ that makes it painful to achieve a certain result. However, the resulting quality of this format chain is good: proper Docbook output, even proper Texinfo output, well-formatted manual pages, nice-looking HTML. In most of those areas, the Texinfo toolchain, in contrast, falls on its face. If one does not want to sacrifice quality, it might still make sense to cut Asciidoc out of the equation and use Docbook instead. Markup-free .txt-files can presumably generated from Docbook. I think it should also be possible to generate manpages from it, and it converts nicely into Texinfo. As long as we have no dedicated Asciidoc wizard working for git, this might make changing the structure of the documentation or adding new features much easier. But it might frighten people from correcting the straight text of the documentation. It is certainly a multi-edged sword, and without doing an extensive poll among those who contribute to documentation, a change in policy would not appear appropriate. I know that the combined Asciidoc/Docbook challenge has kept me up to now from succeeding in a restructuring that would include the manual pages in the user manual as an appendix. I have no doubt from the Docbook and Asciidoc documentation I have digged through that this is possible, and with not too many lines of code, but it is still quite beyond me given the time I can spend on it. The question is how often Asciidoc will keep people from contributing useful changes, and how often Docbook would. I have no idea how the numbers would turn out. I consider it more likely that people will contribute text changes to Asciidoc documentation, but structural changes are likely quite easier to do with Docbook. -- David Kastrup - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
