From: Guenter M. <mi...@us...> - 2012-09-06 23:37:49
|
On 2012-09-05, Michał Górny wrote: > On Wed, 5 Sep 2012 12:32:34 +0000 (UTC) > Guenter Milde <mi...@us...> wrote: >> On 2012-09-03, Michał Górny wrote: >> > On Mon, 3 Sep 2012 21:27:00 +0000 (UTC) >> > Guenter Milde <mi...@us...> wrote: Dear Michał, I understand your concerns about the semantic correctness of the HTML output. I strongly support the concept of semantic markup of a document source. When discussing markup of definition terms with reStructuredText, the following 3 domains should be considered separately (but not completely independent): a) reStructuredText syntax b) the Doctutils document model c) HTML output (and other output formats) The following is a classical example of misunderstanding: >> >> What is the benefit of a pre-defined role over a custom one? >> >> Does it outwight the added complexity? >> > Semantic correctness. >> Semantic markup is a primary use case for custom roles. Define and use >> the roles that suit the needs of the document, for example:: >> .. role:: definition >> .. role:: trademark >> .. role:: informal >> Viewing online content with an :acronym:`HTML` viewer like >> :trademark:`firefox` is called :definition:`browsing` or >> :informal:`surfing`. >> I don't think that pre-defined roles are "more correct" than custom >> ones. ><span class="definition"/> means nothing to a standards-compliant HTML > browser. On the other hand, <dfn/> has a pre-defined meaning which can > be used by a more advanced HTML parsing engine to achieve some goal. Agreed. However, my argument was about the reStructuredText source but the response concerns the HTML output. But also this is theory: Is there an example of a parsing engine that makes use of the <dfn> tag beyond "meaningless styling"? > Shortly saying, <span/> is as meaningful as no tag. So what's the point > of defining it? Except for the fact that you can add *meaningless* > styling with CSS. A generic markup tag makes it possible to add "local semantic markup" to the markup constructs provided by the language core. Basing the extension on the standard markup provides "graceful degradation", e.g. .. role:: definition(emphasis) would present the definition term in a commonly used form without need for a custom CSS style sheet but add the special meaning to the source and the document tree. A matching XSLT stylesheet could be used to extract the meaning from the Docutils XML or (X)HTML output. ... >> Imagine the problems it would make to add a new element and markup >> tag to HTML. Also imagine the problems it makes to remove an element >> and markup tag from the specification of a formal language. > You mean like HTML5? ... No, I meant the discussion and work and documentation requirements involved in going from one version to the next. I wanted to make clear that adding a pre-defined role is not a "quick fix" and requires discussion and careful consideration. And why it is a work that may overstretch the limited ressources available for Docutils development. >> This is why I prefer the flexible and simple way to extend the set of >> semantic markup roles: the "role" directive. > It's not semantic. Unless you add a post-processor which would actually > transform it into something meaningful. Using roles results in semantic markup in the rst source whether these are pre-defined or custom roles. And yes, the output could be post-processed to extract the meaning of the semantic markup. However, the most common use case is still presentation which works out of the box. The Docutils FAQ (not written by me) puts it so: HTML is being used for dumb formatting for nothing but final display. A stylesheet is required, and one is provided; -- http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why Summary: a) Add a pre-defined :definition: role to rst syntax? +1 easy to map to the <dfn> HTML element +1 precedence: the (undocumented) acronym and abbreviation roles +1 the existence of a pre-defined role may encourage people to actually do proper semantic markup of definition terms (did this work in HTML?). -1 one more special markup to document and remember. -1 Should it be called "definition" or "dfn". -2 Proliferation: Why "definition" but not ... The existence of a matching tag in one of the supported output formats is a hint that this may be worth considering. The non-existence in all other output formats should be considered, too. The non-existence of the role in reStructuredText may be the result of careful consideration and not neglect. After all, the <dfn> HTML tag existed before the development of reStructuredText by David Godger. b) Add a "definition" element to the Docutils document model and a "definition" node class to nodes.py -2 Proliferation. -2 Update required for all writers (writers must handle all existing node classes). Using <inline class="definition"> is the safe alternative, using <emphasis class="definition"> provides for graceful degradation. c) let Docutils generate <dfn> tags for definition terms HTML output? +1 The html writer could transform <inline class="definition">, <inline class="dfn">, <emphasis class="definition">, and/or <emphasis class="dfn"> to a <dfn> html tag. -1 Another special case to document. Günter |