On Apr 22, 2010, at 9:55 PM, Sergiu Dumitriu wrote:
> On 04/22/2010 09:04 AM, Vincent Massol wrote:
>> I'm not sure I agree with this patch (even though it might be right
>> from a semantic POV), at least not before we discuss it and decide
>> voluntarily that we want to change our existing terminology.
>>
>> We call them headers and not headings at the moment. This is true
>> both in the language we use and in the technical code (HeaderBlock, etc).
>
> We call them wrong. A header is not the same as a heading, and just
> because we're using a wrong terminology in too many places, doesn't mean
> that we can ignore semantics. If we were to call them heders (typo
> intentional) I'm sure nobody would complain about correcting the typo.
>
>> So if we want to change that, we'll need to :
>> - modify the documentation (xwiki.org and javadoc)
>> - modify the class names in the code (HeadingBlock, HeadingLevel, etc)
>
> Yes, we want to use the correct terms, headers for headers (table
> headers), headings for headings (section titles). But I don't think that
> we need to do this in one full sweep. The syntax page is fairly
> standalone, it definitely doesn't depend on the classes we use in the
> java code. People that consult the syntax help want to know how to write
> a heading in a wiki page, they really don't care that the java class
> that implements them is called HeaderBlock or HeadingLevel. Do you
> really want to oppose documentation improvement just because the inner
> code is still wrong?
No, but consistency is always better so I wanted to make sure that header
couldn't be used in this context (i.e. that it is really wrong).
I've done some research and I couldn't find a single place yet where section
titles are called headers ("section headers" might have some rationale though
but indeed heading seems a better word). They're indeed called headings in most
places.
- WikiModel has it wrong too and calls them Headers.
- Doxia calls them Section Titles
So I now agree that we should move globally towards Heading.
> Now, back to plans, we should update the rest of the documentation if it
> is wrong. And renaming the java classes should be done sooner rather
> than later, while we don't have too many external users of the codebase.
We can go through a deprecation phase. I've created a jira issue:
jira.xwiki.org/jira/browse/XWIKI-5132
>
>> Since it's a big change I'm not sure we want it.
>
> Correcting the syntax page is not a big change.
I was referring to change throughout the project.
>> Also note that this has nothing to do with HTML so even though HTML
>> might call them headings it doesn't matter for us (our syntax is
>> independant or the renderer syntax).
>
> header != heading. It's not about how the HTML spec calls them, it's
> about calling a duck a goose, and insisting on calling it a goose even
> if it isn't one.
Yep, after some research I agree.
Thanks
-Vincent
>
>> WDYT?
>>
>> Thanks
>> -Vincent
>>
>> On Apr 22, 2010, at 12:56 AM, sdumitriu (SVN) wrote:
>>
>>> Author: sdumitriu
>>> Date: 2010-04-22 00:56:11 +0200 (Thu, 22 Apr 2010)
>>> New Revision: 28505
>>>
>>> Modified:
>>> enterprise/trunk/wiki/src/main/resources/XWiki/XWikiSyntax.xml
>>> Log:
>>> XE-647: Misuse of the "header" term instead of "heading" when referring to
>>> the html h1-6
>>> Fixed.
>>> Patch from Dan Bozaru applied without changes.
>>>
>>> Modified: enterprise/trunk/wiki/src/main/resources/XWiki/XWikiSyntax.xml
>>> ===================================================================
>>> --- enterprise/trunk/wiki/src/main/resources/XWiki/XWikiSyntax.xml
>>> 2010-04-21 22:55:34 UTC (rev 28504)
>>> +++ enterprise/trunk/wiki/src/main/resources/XWiki/XWikiSyntax.xml
>>> 2010-04-21 22:56:11 UTC (rev 28505)
>>> @@ -85,7 +85,7 @@
>>> |Two standalone elements not separated by 2 new lines|{{{| table
>>> cell}}}\\{{{* list item}}}|{{{| table cell}}}\\\\{{{* list item}}}
>>> |Two standalone elements not separated by 2 new
>>> lines|{{{paragraph}}}\\{{{----}}}\\{{{paragraph}}}|{{{paragraph}}}\\\\{{{----}}}\\\\{{{paragraph}}}
>>> |Ignored new line at beginning of document|<new line at beginning of
>>> document>\\paragraph|paragraph
>>> -|Not closed header syntax|{{{=== header}}}|{{{=== header ===}}}
>>> +|Not closed heading syntax|{{{=== heading}}}|{{{=== heading ===}}}
>>>
>>> = Paragraphs =
>>>
>>> @@ -102,11 +102,11 @@
>>> |Two paragraphs|Paragraph one\\\\Paragraph two|Paragraph one\\\\Paragraph
>>> two|Paragraph one\\\\Paragraph two|Paragraph one\\\\Paragraph two
>>> |Parametrized paragraph|<p
>>> style="text-align:center;color:blue">Centered and blue
>>> paragraph</p>|{{{(% style="text-align:center;color:blue"
>>> %)}}}\\Centered and blue paragraph|(% style="text-align:center;color:blue"
>>> %)\\Centered and blue paragraph|(% style="text-align:center;color:blue"
>>> %)\\Centered and blue paragraph
>>>
>>> -= Headers =
>>> += Headings =
>>>
>>> (% style="width:100%" %)
>>> |=Feature|=XWiki Syntax 1.0|=XWiki Syntax 2.0|=Result
>>> -|Standard headers|(((
>>> +|Standard headings|(((
>>> 1 level 1
>>> 1.1 level 2
>>> 1.1.1 level 3
>>> @@ -125,11 +125,11 @@
>>> <!-- Note: replace this with wiki syntax when
>>> http://jira.xwiki.org/jira/browse/XWIKI-4358 is implemented -->
>>> <h1 id="Hlevel1"><span>level
>>> 1</span></h1><p>&nbsp;</p><h2
>>> id="Hlevel2"><span>level 2</span></h2><h3
>>> id="Hlevel3"><span>level 3</span></h3><h4
>>> id="Hlevel4"><span>level 4</span></h4><h5
>>> id="Hlevel5"><span>level 5</span></h5><h6
>>> id="Hlevel6"><span>level 6</span></h6>
>>> {{/html}})))
>>> -|Parametrized headers|<h1><span
>>> style="color:blue">header</span></h1>|{{{(%
>>> style="color:blue" %)}}}\\= header =|(((
>>> +|Parametrized headings|<h1><span
>>> style="color:blue">heading</span></h1>|{{{(%
>>> style="color:blue" %)}}}\\= heading =|(((
>>> {{html}}
>>> -<h1 id="Hheader"
>>> style="color:blue"><span>header</span></h1>
>>> +<h1 id="Hheading"
>>> style="color:blue"><span>heading</span></h1>
>>> {{/html}})))
>>> -|Headers with wiki syntax|1.1.1 Header with *bold*|{{{=== Header with
>>> **bold** ===}}}|(((=== Header with **bold** ===)))
>>> +|Headings with wiki syntax|1.1.1 Heading with *bold*|{{{=== Heading with
>>> **bold** ===}}}|(((=== Heading with **bold** ===)))
>>>
>>> = Text Formatting =
>>>
>>> @@ -829,12 +829,12 @@
>>> (% style="width:100%" %)
>>> |=XWiki Syntax 1.0|=XWiki Syntax 2.0|=Generated XHTML
>>> |((({{{
>>> -<h1 class="myClass" style="myStyle" id="myId">header</h1>
>>> +<h1 class="myClass" style="myStyle" id="myId">heading</h1>
>>> }}})))|((({{{
>>> (% class="myClass" style="myStyle" id="myId" %)
>>> -= header =
>>> += heading =
>>> }}})))|((({{{
>>> -<h1 class="myClass" style="myStyle" id="myId">header</h1>
>>> +<h1 class="myClass" style="myStyle" id="myId">heading</h1>
>>> }}})))
>>>
>>> {{id name="syntaxes"/}}
>>> @@ -848,4 +848,4 @@
>>> * [[Creole 1.0>>http://www.wikicreole.org/wiki/Creole1.0]]
>>> * [[XHTML 1.0>>http://www.w3.org/TR/xhtml1/]]
>>>
>>> -{{warning}}The implementation for these syntaxes is not fully finished
>>> yet. For example support for links is not working perfectly yet. We also
>>> need to define if we want to extend the original syntaxes to support
>>> XWiki-specific features like ability to link to another
>>> sub-wiki.{{/warning}}</content></xwikidoc>
>>> \ No newline at end of file
>>> +{{warning}}The implementation for these syntaxes is not fully finished
>>> yet. For example support for links is not working perfectly yet. We also
>>> need to define if we want to extend the original syntaxes to support
>>> XWiki-specific features like ability to link to another
>>> sub-wiki.{{/warning}}</content></xwikidoc>
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
