Details

    • Type: Improvement Improvement
    • Status: Closed Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 3.0
    • Fix Version/s: 5.3-milestone-2
    • Component/s: Help
    • Labels:
    • Difficulty:
      Unknown
    • Pull Request Status:
      Awaiting Committer feedback
    • Similar issues:

      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

          Activity

          Hide
          Vincent Massol added a comment -

          note that since we're releasing 5.3M2 today, this might need a new issue

          Show
          Vincent Massol added a comment - note that since we're releasing 5.3M2 today, this might need a new issue
          Hide
          Vincent Massol added a comment -

          Another "bug", this sentence needs to be modifed: "To fix these a new, as of now experimental, XWiki Syntax 2.1 was introduced in XWiki Enterprise version 3.0. ". It's not experimental anymore.... I don't think we need to reference XE 3.0 anymore either since that's old now.

          I'd say something like;

          Since the introduction of XWiki Syntax 2.0 a few shortcomings of this syntax have been found. Specifically, XWiki Syntax 2.1 improves on:

          • Homogenize the link and image syntax for better clarity, consistency and extensibility.
          • Added ability to display icons, to link to files using the UNC notation and to link to relative URLs.
          Show
          Vincent Massol added a comment - Another "bug", this sentence needs to be modifed: "To fix these a new, as of now experimental, XWiki Syntax 2.1 was introduced in XWiki Enterprise version 3.0. ". It's not experimental anymore.... I don't think we need to reference XE 3.0 anymore either since that's old now. I'd say something like; Since the introduction of XWiki Syntax 2.0 a few shortcomings of this syntax have been found. Specifically, XWiki Syntax 2.1 improves on: Homogenize the link and image syntax for better clarity, consistency and extensibility. Added ability to display icons, to link to files using the UNC notation and to link to relative URLs.
          Hide
          Vincent Massol added a comment -

          This issue is missing documentation (There's an "NA" in this issue's documentation field but that's not normal since this issue was an improvement so it has to be documented ).

          Clemens, do you think you could document the changes on http://extensions.xwiki.org/xwiki/bin/view/Extension/Help+Application (update the existing screenshot, add some more, add 1 or 2 lines of text to explain the new features)?

          Thanks!

          Show
          Vincent Massol added a comment - This issue is missing documentation (There's an "NA" in this issue's documentation field but that's not normal since this issue was an improvement so it has to be documented ). Clemens, do you think you could document the changes on http://extensions.xwiki.org/xwiki/bin/view/Extension/Help+Application (update the existing screenshot, add some more, add 1 or 2 lines of text to explain the new features)? Thanks!
          Hide
          Clemens Robbenhaar added a comment - - edited

          I have updated the help page a little.
          I also have created XWIKI-9899 for the improvements mentioned in the comments above, as I plain forgot about them after this issue has been closed.

          Show
          Clemens Robbenhaar added a comment - - edited I have updated the help page a little. I also have created XWIKI-9899 for the improvements mentioned in the comments above, as I plain forgot about them after this issue has been closed.
          Hide
          Vincent Massol added a comment -

          Thanks Clemens

          Show
          Vincent Massol added a comment - Thanks Clemens

            People

            • Assignee:
              Clemens Robbenhaar
              Reporter:
              Johannes Stoldt
            • Votes:
              2 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:
                Date of First Response: