Affects Version/s: 3.0
Fix Version/s: 5.3-milestone-2
keywords:Syntax,Guide, ux, usability
Documentation in Release Notes:
Pull Request Status:Awaiting Committer feedback
XWIKI-9756 New XWiki Syntax guide lists every section twice XWIKI-117 Switching to GUID for document and objects XWIKI-1969 Can Guide me how to create struts-hibernate integrated xwiki plug-in XWIKI-486 Import XWiki Admin Guide in new XWiki.org XWIKI-5487 Introduce XWiki Syntax 2.1 XWIKI-2766 TOC doesn't work with "new" heading syntax (Page Syntax: XWiki 1.0) XWIKI-3608 Set new blog posts to be created in XWiki 2.0 syntax XWIKI-3607 Set new user profiles to be created in XWiki 2.0 syntax XWIKI-2962 Write automatic converter from XWiki Syntax 1.0 to XWiki Syntax 2.0 XWIKI-498 Create a User Guide
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:
- 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)
- Level 2 heading: Holds the name of the section
- 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:
While content and section/category names can be translated by just translating the syntax pages the following three ApplicationRessources will have to be added:
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.