Click
  1. Click
  2. CLK-482

Convert documentation to Docbook

    Details

    • Type: New Feature New Feature
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.0.1
    • Fix Version/s: 2.1.0
    • Component/s: documentation
    • Labels:
      None

      Description

      By converting the documentation to Docbook format we gain the ability to generate PDF and HTML output, which is easier to search and find information.

      1. click.zip
        35 kB
        Gilberto C Andrade
      2. imagem.PNG
        59 kB
        Gilberto C Andrade
      3. chapter-controls.xml
        35 kB
        Gilberto C Andrade
      4. chapter-configuration.xml
        37 kB
        Gilberto C Andrade
      5. click-docbook.zip
        36 kB
        Gilberto C Andrade
      6. chapter-configuration.xml
        38 kB
        Gilberto C Andrade
      7. chapter-controls.xml
        35 kB
        Gilberto C Andrade
      8. src.tar.gz
        167 kB
        Gilberto C Andrade

        Activity

        Hide
        Gilberto C Andrade added a comment -

        Ok, I'm ready to start!
        I will begin with controls chapter and create chapter-controls.xml file.

        Show
        Gilberto C Andrade added a comment - Ok, I'm ready to start! I will begin with controls chapter and create chapter-controls.xml file.
        Hide
        Gilberto C Andrade added a comment -

        Done with chapter-controls.xml.

        I've converted:
        /click/chapter-best-practices.xml
        /click/chapter-configuration.xml
        /click/chapter-controls.xml
        /click/chapter-introduction.xml
        /click/chapter-pages.xml

        But only chapter-controls.xml conforms with chapter-instroduction.xml right now. First I need you check. If it is ok - controls.xml -, then I will continue with the other files.

        Show
        Gilberto C Andrade added a comment - Done with chapter-controls.xml. I've converted: /click/chapter-best-practices.xml /click/chapter-configuration.xml /click/chapter-controls.xml /click/chapter-introduction.xml /click/chapter-pages.xml But only chapter-controls.xml conforms with chapter-instroduction.xml right now. First I need you check. If it is ok - controls.xml -, then I will continue with the other files.
        Hide
        Bob Schellink added a comment -

        Good work Gilberto. I've checked everything in.

        The generated PDF is a full 74 pages

        Show
        Bob Schellink added a comment - Good work Gilberto. I've checked everything in. The generated PDF is a full 74 pages
        Hide
        Gilberto C Andrade added a comment -

        chapter-controls.xml – Missing ids

        chapter-configuration.xml – I think it is ok.

        Show
        Gilberto C Andrade added a comment - chapter-controls.xml – Missing ids chapter-configuration.xml – I think it is ok.
        Hide
        Bob Schellink added a comment -

        I think the "anchor-" prefix can be removed as the id's are unique across all pages. Makes the HTML bookmark a little shorter too

        Show
        Bob Schellink added a comment - I think the "anchor-" prefix can be removed as the id's are unique across all pages. Makes the HTML bookmark a little shorter too
        Hide
        Gilberto C Andrade added a comment -

        I've followed you suggestion and changed the other files as well!
        Let's see if they are all ok.

        Show
        Gilberto C Andrade added a comment - I've followed you suggestion and changed the other files as well! Let's see if they are all ok.
        Hide
        Gilberto C Andrade added a comment -

        Is that index correct?

        4. Configuration
        4.1. 1. Servlet Configuration
        1.1 Servlet Mapping
        1.2 Load On Startup
        4.2. 2. Application Configuration
        2.1 Click App
        2.2 Pages
        2.3 Page
        2.4 Headers

        Show
        Gilberto C Andrade added a comment - Is that index correct? 4. Configuration 4.1. 1. Servlet Configuration 1.1 Servlet Mapping 1.2 Load On Startup 4.2. 2. Application Configuration 2.1 Click App 2.2 Pages 2.3 Page 2.4 Headers
        Hide
        Bob Schellink added a comment -

        You're right, the indexing is wrong. I think its because the HTML docs uses manual indexing which is why we get:

        4.1. 1 Servlet Configuration

        It should be:

        4.1 Servlet Configuration

        Since docbook takes care of indexing automatically we should remove the manual indexing from the docs.

        Btw the docs from the latest click-docbook.zip attachment, replaced the non-breaking space ( ) with the character 'Â'.

        Show
        Bob Schellink added a comment - You're right, the indexing is wrong. I think its because the HTML docs uses manual indexing which is why we get: 4.1. 1 Servlet Configuration It should be: 4.1 Servlet Configuration Since docbook takes care of indexing automatically we should remove the manual indexing from the docs. Btw the docs from the latest click-docbook.zip attachment, replaced the non-breaking space ( ) with the character 'Â'.
        Hide
        Gilberto C Andrade added a comment -

        [quote]
        Since docbook takes care of indexing automatically we should remove the manual indexing from the docs.
        [/quote]
        You mean that we won't use any numbering!

        [quote]
        Btw the docs from the latest click-docbook.zip attachment, replaced the non-breaking space ( ) with the character 'Â'.
        [/quote]
        Interesting! I've just download it and didn't find that character. How can I see and remove it?

        Other thing, I'm using eclipse to check it out and edit the files. When I use the compare editor with svn repository, there aren't any problems with my work.

        Show
        Gilberto C Andrade added a comment - [quote] Since docbook takes care of indexing automatically we should remove the manual indexing from the docs. [/quote] You mean that we won't use any numbering! [quote] Btw the docs from the latest click-docbook.zip attachment, replaced the non-breaking space ( ) with the character 'Â'. [/quote] Interesting! I've just download it and didn't find that character. How can I see and remove it? Other thing, I'm using eclipse to check it out and edit the files. When I use the compare editor with svn repository, there aren't any problems with my work.
        Hide
        Bob Schellink added a comment -

        Nods there should be no need for numbering.

        As for the   character replacement, I think what happened was that when the html docs was converted, the non-breaking space character was encoded into UTF-8. If you use UTF-8 to view it, then you should see two spaces. On my Windows box however I see the  follows by space.

        Don't worry about it though, I'll convert  back to   before checking it in, which I'll do now

        Show
        Bob Schellink added a comment - Nods there should be no need for numbering. As for the   character replacement, I think what happened was that when the html docs was converted, the non-breaking space character was encoded into UTF-8. If you use UTF-8 to view it, then you should see two spaces. On my Windows box however I see the  follows by space. Don't worry about it though, I'll convert  back to   before checking it in, which I'll do now
        Hide
        Gilberto C Andrade added a comment -

        I've seen you changes, but didn't understand the new tags!
        Would you mind to explain the idea? This way I can help on the other ones.

        Show
        Gilberto C Andrade added a comment - I've seen you changes, but didn't understand the new tags! Would you mind to explain the idea? This way I can help on the other ones.
        Hide
        Bob Schellink added a comment -

        Made the following changes:

        1. converted <screen> to <programlisting>
        1. removed the generated <anchor> tags and moved the <anchor> id attribute to the corresponding <section>. Since docbook takes care of bookmarking and indexing, the <anchor> tags are redundant.

        To remove the redundant markup look for code such as:

        <anchor id="configuration-click-logging"/>
        <indexterm>
        <primary>click-logging</primary>
        </indexterm>
        <sect1 remap="h1">

        Then move the anchor attribute "id=configuration-click-logging" to sect1:

        <sect1 id="configuration-click-logging" remap=h1">

        and delete the <anchor>, <indexterm> and <primary> tags.

        Show
        Bob Schellink added a comment - Made the following changes: converted <screen> to <programlisting> removed the generated <anchor> tags and moved the <anchor> id attribute to the corresponding <section>. Since docbook takes care of bookmarking and indexing, the <anchor> tags are redundant. To remove the redundant markup look for code such as: <anchor id="configuration-click-logging"/> <indexterm> <primary>click-logging</primary> </indexterm> <sect1 remap="h1"> Then move the anchor attribute "id=configuration-click-logging" to sect1: <sect1 id="configuration-click-logging" remap=h1"> and delete the <anchor>, <indexterm> and <primary> tags.
        Hide
        Gilberto C Andrade added a comment -

        Both controls.xml and configuration.xml files have numbering in some title tags and nothing in other title tags.
        Can I remove these ones?

        Show
        Gilberto C Andrade added a comment - Both controls.xml and configuration.xml files have numbering in some title tags and nothing in other title tags. Can I remove these ones?
        Hide
        Bob Schellink added a comment -

        Yep those can be removed.

        Show
        Bob Schellink added a comment - Yep those can be removed.
        Hide
        Gilberto C Andrade added a comment -

        Would you mind to explain the idea about the prefix on section tags (image)?
        I'm trying to find a pattern and apply it to the other files.

        Show
        Gilberto C Andrade added a comment - Would you mind to explain the idea about the prefix on section tags (image)? I'm trying to find a pattern and apply it to the other files.
        Hide
        Bob Schellink added a comment -

        There is no pattern really. The section ID's just need to be unique across the entire book.
        However we should try and keep the existing bookmarks in tact. For example in your screenshot the 'application' prefix exist in the current documentation:

        http://incubator.apache.org/click/docs/configuration.html#application-click-app
        http://incubator.apache.org/click/docs/configuration.html#application-pages

        Show
        Bob Schellink added a comment - There is no pattern really. The section ID's just need to be unique across the entire book. However we should try and keep the existing bookmarks in tact. For example in your screenshot the 'application' prefix exist in the current documentation: http://incubator.apache.org/click/docs/configuration.html#application-click-app http://incubator.apache.org/click/docs/configuration.html#application-pages
        Hide
        Gilberto C Andrade added a comment -

        Let's see if the work was done correctly this time, rs rs rs!
        I hope so!

        Show
        Gilberto C Andrade added a comment - Let's see if the work was done correctly this time, rs rs rs! I hope so!
        Hide
        Bob Schellink added a comment -

        Looks very good. I think the conversion is nearly finished.

        I'll be reformatting the docs (some paragraphs are very long) which will touch all source. I suggest you wait until the reformatted code is checked in before making further changes.

        Show
        Bob Schellink added a comment - Looks very good. I think the conversion is nearly finished. I'll be reformatting the docs (some paragraphs are very long) which will touch all source. I suggest you wait until the reformatted code is checked in before making further changes.
        Hide
        Bob Schellink added a comment -

        I think the doc conversion went very well and can be closed. Thanks to Gilberto for his work on this.

        Show
        Bob Schellink added a comment - I think the doc conversion went very well and can be closed. Thanks to Gilberto for his work on this.

          People

          • Assignee:
            Bob Schellink
            Reporter:
            Bob Schellink
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development