XWiki Platform

New XWiki Syntax Guide

Details

  • Type: Improvement Improvement
  • Status: Open Open
  • Priority: Major Major
  • Resolution: Unresolved
  • Affects Version/s: 3.0
  • Fix Version/s: None
  • Component/s: Help
  • Labels:
    None
  • keywords:
    Syntax,Guide, ux, usability
  • Difficulty:
    Unknown
  • Similar issues:
    XWIKI-117Switching to GUID for document and objects
    XWIKI-1969Can Guide me how to create struts-hibernate integrated xwiki plug-in
    XWIKI-486Import XWiki Admin Guide in new XWiki.org
    XWIKI-5487Introduce XWiki Syntax 2.1
    XWIKI-2766TOC doesn't work with "new" heading syntax (Page Syntax: XWiki 1.0)
    XWIKI-3608Set new blog posts to be created in XWiki 2.0 syntax
    XWIKI-3607Set new user profiles to be created in XWiki 2.0 syntax
    XWIKI-2962Write automatic converter from XWiki Syntax 1.0 to XWiki Syntax 2.0
    XWIKI-498Create a User Guide
    XWIKI-2674Add style support in new XWiki 2.0 table syntax

Description

In the last few weeks I built a new Syntax Guide following the third suggestion of Ecaterina Valica (see: http://incubator.myxwiki.org/xwiki/bin/view/Improvements/SyntaxExperiments3 ). This one is based on the new 3.0 Admin app that has been created by... Sergiu, IIRC.

You will find the Guide I built in the attached .xar file. I would just like to point a couple of things about the code.

  • Every section displayed in the guide is placed on a single document that should ideally be named something like XWikiSyntaxNewSection
  • Every section page should have the following outline:
    1. Level 1 heading: Holds the name of the category in which the section is displayed (will be retrieved from first section to be added to a category)
    2. Level 2 heading: Holds the name of the section
    3. Level 5 headings: One heading/section for each version of the syntax information to be displayed. Heading must be the appropriate version number (e.g. "===== 2.0 =====")
  • The XWikiSyntaxClass holds the following information and has to be attached to every section page:
    • category: The 0-based number of the category in which the section should be displayed.
    • section: The 0-based number at which the section should be displayed within the category.
    • minSyntaxVersion: The first syntax version for which syntax information is available (if the selected version is smaller than this value the section will be hidden)
    • maxSyntaxVersion: The last syntax version for which syntax information is available (if the selected version is greater than this value the last available version will be displayed)
  • In order to display the version numbering according to the current selection despite actually displaying section of previous version (see maxSyntaxVersion) the version number should be replaced as follows:
2.0 -> {{velocity}}$crtSyntaxVer{{/velocity}}

While content and section/category names can be translated by just translating the syntax pages the following three ApplicationRessources will have to be added:

xe.syntax.syntaxpage.title=XWiki Syntax Guide
xe.syntax.syntaxtitle=XWiki Syntax {0}
xe.syntax.syntaxall=All

See the attached xar package for the sources to the entire guide. Content-wise it is roughly what has been in the latest revision of the "old" Syntax Guide.

Issue Links

is related to

Improvement - An improvement or enhancement to an existing feature or task. XWIKI-9177 Adds a form to try out wiki markup in the Syntax help page

  • Minor - Minor loss of function, or other problem where easy workaround is present.
  • Open - The issue is open and ready for the assignee to start work on it.

Improvement - An improvement or enhancement to an existing feature or task. XE-429 Adapt syntax help depending of syntax used on the page

  • Trivial - Cosmetic problem like misspelt words or misaligned text.
  • Closed - The issue is considered finished, the resolution is correct and has been pushed to production. Issues which are not closed can be reopened.

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Ecaterina Moraru (Valica) added a comment -

1) You need to add
$xwiki.ssx.use("XWiki.XWikiSyntax")
for the style to be applied. After community validation we can add #change-context style to colibri.css instead of duplicating the code from administration.

2) There are two #document-info. This is not good from a validation point of view and also because if you'd want to hide the page title from CSS and leave the generated title you can't because they are using the same ids. Same for #hierarchy.

3) All <table style="width:100%"> need to be <table style="width:99%"> in order to be on the safe side on all browsers. We can have this styling from CSS too. Also "Warning: <table> lacks "summary" attribute" for all the tables.

4) I don't like that you used h5 headers. WCAG is broken, because headers are not consecutive, also there is no semantic value added, also you hide them from CSS so it's not a matter of styling either. The validation will show you "Warning: <h5> anchor "H2.0" already defined" so you shouldn't use ids too. The solution IMO is to have .div with classes.

Show
Ecaterina Moraru (Valica) added a comment - 1) You need to add $xwiki.ssx.use("XWiki.XWikiSyntax") for the style to be applied. After community validation we can add #change-context style to colibri.css instead of duplicating the code from administration. 2) There are two #document-info. This is not good from a validation point of view and also because if you'd want to hide the page title from CSS and leave the generated title you can't because they are using the same ids. Same for #hierarchy. 3) All <table style="width:100%"> need to be <table style="width:99%"> in order to be on the safe side on all browsers. We can have this styling from CSS too. Also "Warning: <table> lacks "summary" attribute" for all the tables. 4) I don't like that you used h5 headers. WCAG is broken, because headers are not consecutive, also there is no semantic value added, also you hide them from CSS so it's not a matter of styling either. The validation will show you "Warning: <h5> anchor "H2.0" already defined" so you shouldn't use ids too. The solution IMO is to have .div with classes.
Hide
Permalink
Johannes Stoldt added a comment -

1) My bad. It's there and it used to work, only problem is that I renamed the page before I created the .xar and missed it. Search for XWikiSyntaxNew occurences.

2) It took me a while to understand what you meant but to be honest, I have no idea why it's in the Syntax Guide but not in the Admin App... Might it be that some different processing is used when using /bin/admin/ compared to /bin/view/? Either way, I have not the slightest clue on how to fix that.

3) Changing the width to 99% is not a bother for me but what do you mean by "summary" attribute? I used regular table syntax (the same as in the old Syntax Guide, actually) and only added the styles (like they were in the old Syntax Guide).

4) Using h5 headers has a reason. First of all, I did not like to split the content among even more single documents. My original intention was to use one document per version. Then I figured that would give me trouble when including documents, especially because at that point there was no getSections. Now we got getSections but it only retrieves h1 and h2 headers. Anyway, I had to come up with something else where the headings would be identical in each and every document. I came up with the idea to have a document per section to display that will hold the different revisions of the documentation. This is how it is now. Using h5 headings was my way of choice in order to minimize trouble when extending while retaining an easy way to hide the heading, which is unfortunately also included when using the include macro.

With this pretext given, the only two possible ways to act on what you said would be the following: 1. Somebody has to implement a public function that allows me to retrieve all sections so I can use only one document per Syntax version. 2. I have to split the sections on a one-document-per-section-and-version basis which will generate approx. twice as many documents as the currently presented version has already. The first is obviously not bad but what I took from my conversations with Thomas was that 1. is actually part of a bigger part that is on the todo list. I really don't like the latter because, like I said, it just keeps piling on, basically.

Lastly, I did have to use sections because they are the only things I can include using the include macro. Trying to include IDs ended in failure. Even trying something like the below failed:

(% id="syntaxes %)(((
some text
)))
Show
Johannes Stoldt added a comment - 1) My bad. It's there and it used to work, only problem is that I renamed the page before I created the .xar and missed it. Search for XWikiSyntaxNew occurences. 2) It took me a while to understand what you meant but to be honest, I have no idea why it's in the Syntax Guide but not in the Admin App... Might it be that some different processing is used when using /bin/admin/ compared to /bin/view/? Either way, I have not the slightest clue on how to fix that. 3) Changing the width to 99% is not a bother for me but what do you mean by "summary" attribute? I used regular table syntax (the same as in the old Syntax Guide, actually) and only added the styles (like they were in the old Syntax Guide). 4) Using h5 headers has a reason. First of all, I did not like to split the content among even more single documents. My original intention was to use one document per version. Then I figured that would give me trouble when including documents, especially because at that point there was no getSections. Now we got getSections but it only retrieves h1 and h2 headers. Anyway, I had to come up with something else where the headings would be identical in each and every document. I came up with the idea to have a document per section to display that will hold the different revisions of the documentation. This is how it is now. Using h5 headings was my way of choice in order to minimize trouble when extending while retaining an easy way to hide the heading, which is unfortunately also included when using the include macro. With this pretext given, the only two possible ways to act on what you said would be the following: 1. Somebody has to implement a public function that allows me to retrieve all sections so I can use only one document per Syntax version. 2. I have to split the sections on a one-document-per-section-and-version basis which will generate approx. twice as many documents as the currently presented version has already. The first is obviously not bad but what I took from my conversations with Thomas was that 1. is actually part of a bigger part that is on the todo list. I really don't like the latter because, like I said, it just keeps piling on, basically. Lastly, I did have to use sections because they are the only things I can include using the include macro. Trying to include IDs ended in failure. Even trying something like the below failed: (% id="syntaxes %)((( some text )))
Hide
Permalink
Vincent Massol added a comment - - edited

What's sure if that we need the syntax page to pass the WCAG tests (otherwise the build will fail).

Show
Vincent Massol added a comment - - edited What's sure if that we need the syntax page to pass the WCAG tests (otherwise the build will fail).
Hide
Permalink
Guillaume Laforge added a comment -

It would be nice to have a new syntax guide for the latest official syntax, rather than the one aggregating all the supported syntaxes.

Show
Guillaume Laforge added a comment - It would be nice to have a new syntax guide for the latest official syntax, rather than the one aggregating all the supported syntaxes.

People

  • Assignee:
    Unassigned
    Reporter:
    Johannes Stoldt
Vote (2)
Watch (3)

Dates

  • Created:
    Updated:
    Date of First Response: