Details

    • Type: Bug Bug
    • Status: Closed Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.0-beta-6
    • Fix Version/s: 2.0
    • Component/s: site descriptor
    • Labels:
      None
    • Environment:
      All
    • Number of attachments :
      0

      Description

      There is no documentation for site. I mean there is some, but this is not enough. For example there is no reference what elements can be included in site.xml. What are tags? No clue. It is not possible to use it as it is now. I do understand I can find out what they do by trying, but at least I need to know what they are. I tried to search on internet for any documentation, but no success. It is very frustrating. I think many users give up using it, just because they can not find what it can do and how to use it.
      Please provide at least simple list of the elements that are available in site.xml.

        Issue Links

          Activity

          Hide
          Dennis Lundberg added a comment -

          We have fairly extensive documentation about the site.xml file here:
          http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html

          Isn't that enough?

          Show
          Dennis Lundberg added a comment - We have fairly extensive documentation about the site.xml file here: http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html Isn't that enough?
          Hide
          Alfonsas Stonis added a comment -

          Hi,

          It is really nice to have examples, but I was looking for was reference. I do understand that it covers some part of functionality, but is it all?
          If you look at this example you will find that you can change:
          o) title,
          o) public date,
          o) powered by logo
          o) inheritance
          o) include 3 types of generated content
          o) change skins
          o) and use expressions

          Is this all?
          I doubt it.

          Starting from small things:
          o) publishDate can have format cool, but what is the syntax? You do not need to describe it, reference is enough.
          o) when I inherit something from something I can have menu. Nice. But the code I found has not only menu, but menu items too. They have references, how they are described?
          o) how many levels can be in menu?
          o) what items can be in menu?
          o) what kind of files can be referenced?
          o) which of them are interpreted by site and regenerated?
          o) how files are referenced? I see that there are different files are used in other projects and they are referenced the same, but they are picked from different locations
          o) where is the definition of the files that can be included
          o) schema definition for site.xml would be nice. Documentation is much easier to read, but I can deal with it. Of course I still will have no idea what these items are used for, but at least I will know what can be included in site.xml and validate it.

          I like maven and site plugin. I think it can be useful, but without the information I can do very little with it (change logo for empty document).

          Show
          Alfonsas Stonis added a comment - Hi, It is really nice to have examples, but I was looking for was reference. I do understand that it covers some part of functionality, but is it all? If you look at this example you will find that you can change: o) title, o) public date, o) powered by logo o) inheritance o) include 3 types of generated content o) change skins o) and use expressions Is this all? I doubt it. Starting from small things: o) publishDate can have format cool, but what is the syntax? You do not need to describe it, reference is enough. o) when I inherit something from something I can have menu. Nice. But the code I found has not only menu, but menu items too. They have references, how they are described? o) how many levels can be in menu? o) what items can be in menu? o) what kind of files can be referenced? o) which of them are interpreted by site and regenerated? o) how files are referenced? I see that there are different files are used in other projects and they are referenced the same, but they are picked from different locations o) where is the definition of the files that can be included o) schema definition for site.xml would be nice. Documentation is much easier to read, but I can deal with it. Of course I still will have no idea what these items are used for, but at least I will know what can be included in site.xml and validate it. I like maven and site plugin. I think it can be useful, but without the information I can do very little with it (change logo for empty document).
          Hide
          Dennis Lundberg added a comment -

          Thanks for the list. It makes it much easier for us to know in detail what it is that you (the users) want. I'll try to work on the documentation when I find some time.

          Show
          Dennis Lundberg added a comment - Thanks for the list. It makes it much easier for us to know in detail what it is that you (the users) want. I'll try to work on the documentation when I find some time.
          Hide
          Alfonsas Stonis added a comment -

          Cool. I will be waiting to see updated documentation. Such documentation seems small thing, but it stops me from using and is very frustrating.

          Show
          Alfonsas Stonis added a comment - Cool. I will be waiting to see updated documentation. Such documentation seems small thing, but it stops me from using and is very frustrating.
          Hide
          Herve Boutemy added a comment -

          while publishing site.xml's xsd, there is a documentation published too

          I don't know if it is really sufficient, but it contains answers to a lot of questions

          Show
          Herve Boutemy added a comment - while publishing site.xml's xsd, there is a documentation published too I don't know if it is really sufficient, but it contains answers to a lot of questions
          Hide
          Dennis Lundberg added a comment -
          Show
          Dennis Lundberg added a comment - The correct URL to the site.xml xsd documentation is: http://maven.apache.org/doxia/doxia-sitetools-1.0.x/doxia-decoration-model/decoration.html
          Hide
          Dennis Lundberg added a comment -

          I added links to the XML schema and the XML Schema Reference in r749053.

          Show
          Dennis Lundberg added a comment - I added links to the XML schema and the XML Schema Reference in r749053.

            People

            • Assignee:
              Dennis Lundberg
              Reporter:
              Alfonsas Stonis
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: