Johannes Sixt <j6t@xxxxxxxx> writes: >> Square brackets are possible inside the double-quotes: >> s:["--ignore-submodules[=<when>]"] >> >> Is this something that wouldn't repel you? > > You argued elsewhere in this thread: > >> * The fact that the source of the pages should be "perfectly readable" is a >> moot argument. Fair enough, it is not the objective to make it impossible to >> understand, but in the end, this is not what is consumed: these pages are >> compiled into other formats where the markup has been translated into styling. > > I buy this argument, in particular, since not even I read the plain text > files, but use the rendered version. FWIW, I do read the plain text files, and rarely if ever use the HTML version, except when checking the effect of changes to the mark-up. > I would like tone down my harsh opposition to mild opposition. IMO, it > should still be easy to *write* the documentation. It should not be > necessary that authors remember to use macros all over the place. Yeah, s:[...] does repel me, but also I do not think it is sensible to claim that we confortably edit the "source" form that we find it hard to read. > And I still think that we should not introduce macros just to please all > renderers. Let's just pick the one renderer that can do the job best. If > it means that some distribution cannot render the documentation > perfectly themselves (Debian? I don't know), they can always use the > pre-rendered version that Junio kindly produces. What Junio uses "Debian? I don't know" that cannot render the documentation ;-)?
