Solr
  1. Solr
  2. SOLR-238

[Patch] The tutorial on our website is against trunk which causes confusion by user

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 1.2
    • Component/s: documentation
    • Labels:
      None

      Description

      The patch will add a note to the tutorial page with the following headsup:
      "This is documentation for the development version (TRUNK). Some instructions may only work if you are working against svn head."

      1. SOLR-238.png
        85 kB
        Thorsten Scherler
      2. SOLR-238.diff
        1 kB
        Thorsten Scherler
      3. SOLR-238.diff
        5 kB
        Thorsten Scherler
      4. SOLR-238.diff
        5 kB
        Thorsten Scherler
      5. SOLR-238.diff
        5 kB
        Hoss Man
      6. SOLR-238.diff
        6 kB
        Hoss Man

        Activity

        Hide
        Thorsten Scherler added a comment -

        Patch of the forrest skinconf.xml

        Show
        Thorsten Scherler added a comment - Patch of the forrest skinconf.xml
        Hide
        Thorsten Scherler added a comment -

        screenshot
        Find window title changed and two new note boxes.

        Show
        Thorsten Scherler added a comment - screenshot Find window title changed and two new note boxes.
        Hide
        Hoss Man added a comment -

        Thorsten ... thanks for the prod on this issue. One thing that makes this tricky is that the tutorial (and the entire website) are bundled with every release ... that's why we keep the site up to date with the trunk, so that people can review the docs as time goes on, but when a release is cut people using that release should refer to the docs that come with it.

        I'm not very knowledgeable in forest, do you (or anyone else watching this issue) know if there is an easy way to do variable substitution into the generated docs when they are build using property files (or something like it)

        Then the docs could always contain the current Solr spec version number when the tutorial is regenerated (for official releases, the spec version number looks like 1.1, 1.2, etc... for nightly builds it looks like 1.1.2007.05.11.10.10.53 – the last official version number followed by the current datetime)

        Show
        Hoss Man added a comment - Thorsten ... thanks for the prod on this issue. One thing that makes this tricky is that the tutorial (and the entire website) are bundled with every release ... that's why we keep the site up to date with the trunk, so that people can review the docs as time goes on, but when a release is cut people using that release should refer to the docs that come with it. I'm not very knowledgeable in forest, do you (or anyone else watching this issue) know if there is an easy way to do variable substitution into the generated docs when they are build using property files (or something like it) Then the docs could always contain the current Solr spec version number when the tutorial is regenerated (for official releases, the spec version number looks like 1.1, 1.2, etc... for nightly builds it looks like 1.1.2007.05.11.10.10.53 – the last official version number followed by the current datetime)
        Hide
        Thorsten Scherler added a comment -

        Implementing the solution David suggested in http://marc.info/?t=117916697600003&r=1&w=2

        Now the file you want to generate via e.g. ant (or change it by hand) is src/site/src/documentation/resources/schema/symbols-project-v10.ent

        This allows you to use &solr-v; and it will be substituted with the value defined in symbols-project-v10.ent. More information can be found http://forrest.zones.apache.org/ft/build/forrest-seed/samples/xml-entities.html

        Show
        Thorsten Scherler added a comment - Implementing the solution David suggested in http://marc.info/?t=117916697600003&r=1&w=2 Now the file you want to generate via e.g. ant (or change it by hand) is src/site/src/documentation/resources/schema/symbols-project-v10.ent This allows you to use &solr-v; and it will be substituted with the value defined in symbols-project-v10.ent. More information can be found http://forrest.zones.apache.org/ft/build/forrest-seed/samples/xml-entities.html
        Hide
        Hoss Man added a comment -

        i'm going to try and look into this today or tomorrow ... Thorsten, a couple of quick questions...

        1) is the file name "symbols-project-v10.ent" significant in some way, or can we make it something a little easier for people to understand, like "solr-specific-forrest-variables.ent" ?

        (in particular, the "v10" jumps out at me as being confusing and odd .. version 10 of what?)

        2) is there any reason why forrest would care if the symbols file lives in the resources directory, or can it live anywhere as long as the relative URI in the <!ENTITY> declaration points at the right spot?

        3) what is the purpose of the catalog.xcat file your patch adds?

        Show
        Hoss Man added a comment - i'm going to try and look into this today or tomorrow ... Thorsten, a couple of quick questions... 1) is the file name "symbols-project-v10.ent" significant in some way, or can we make it something a little easier for people to understand, like "solr-specific-forrest-variables.ent" ? (in particular, the "v10" jumps out at me as being confusing and odd .. version 10 of what?) 2) is there any reason why forrest would care if the symbols file lives in the resources directory, or can it live anywhere as long as the relative URI in the <!ENTITY> declaration points at the right spot? 3) what is the purpose of the catalog.xcat file your patch adds?
        Hide
        Thorsten Scherler added a comment -

        cheers Hoss!

        1) yes, you can change the name. I will add a new version.

        2)
        a) no, you can change it in the forrest.properties:
        #project.schema-dir=$

        {project.resources-dir}

        /schema
        is the default.
        You can change it to something like
        project.schema-dir=src/schema
        if you want, just uncomment the property.
        b) not sure about the path better use the forrest.properties.

        3) As I understand it (used it the first time in this contribution) it links to the *. ent file, giving the benefit that you can import it to your favorite xml editor:
        http://forrest.apache.org/docs_0_70/catalog.html
        further (as I understand it) forrest is using it to look up the *.ent file.

        Show
        Thorsten Scherler added a comment - cheers Hoss! 1) yes, you can change the name. I will add a new version. 2) a) no, you can change it in the forrest.properties: #project.schema-dir=$ {project.resources-dir} /schema is the default. You can change it to something like project.schema-dir=src/schema if you want, just uncomment the property. b) not sure about the path better use the forrest.properties. 3) As I understand it (used it the first time in this contribution) it links to the *. ent file, giving the benefit that you can import it to your favorite xml editor: http://forrest.apache.org/docs_0_70/catalog.html further (as I understand it) forrest is using it to look up the *.ent file.
        Hide
        Thorsten Scherler added a comment -

        Using "solr-specific-forrest-variables.ent" as file name as suggested by Hoss.

        Show
        Thorsten Scherler added a comment - Using "solr-specific-forrest-variables.ent" as file name as suggested by Hoss.
        Hide
        Hoss Man added a comment -

        my main question was not about renaming/moving the resources/schema directory .. it was more about making that file live completely outside of src/site/src/documentation/ altogether, so that we could refer directly to something like ../../...../build/solr-specific-forrest-variables.ent

        Show
        Hoss Man added a comment - my main question was not about renaming/moving the resources/schema directory .. it was more about making that file live completely outside of src/site/src/documentation/ altogether, so that we could refer directly to something like ../../...../build/solr-specific-forrest-variables.ent
        Hide
        Thorsten Scherler added a comment -

        Yes you can, you just need to point
        project.schema-dir=../../...../build/solr-specific-forrest-variables.ent
        to the right location.

        Show
        Thorsten Scherler added a comment - Yes you can, you just need to point project.schema-dir=../../...../build/solr-specific-forrest-variables.ent to the right location.
        Hide
        Hoss Man added a comment -

        Thorsten (et al) I'd apprecaite your feedback on this patch revision...

        1) moved the location of the variables file to ./build using a deep ../../ path ... i didn't change the forrest.properties to do this, because I wanted to keep the catalog.xcat where it was since that seems to be standard.

        2) from a clean check out "ant init-forrest-entities" is now a prepreq for forrest to run properly, otherwise the XML doesn't validate because the entities can't resolve. most of hte core ant tasks take care of this via dependencies.

        a couple of notes about the specifics...

        a) i used the "specversion" since it's the most precise of our version numbers, it contains the datetime of dev builds, and is the number you would expect for official builds
        b) i tried to make the entity name consistent with the property name so that if someone smarter then me knows a way to get ant to dump all properties using a <filterchain> we can refer to any ant properties as entities not just solr.specversion
        c) if committed, Website_Update_HOWTO needs note about "ant init-forrest-entities"
        d) if committed, HowToRelease needs updated to indicate that the docs on the branch need regenerated/commited after building/testing the code sith specversion set, but before packaging.

        Show
        Hoss Man added a comment - Thorsten (et al) I'd apprecaite your feedback on this patch revision... 1) moved the location of the variables file to ./build using a deep ../../ path ... i didn't change the forrest.properties to do this, because I wanted to keep the catalog.xcat where it was since that seems to be standard. 2) from a clean check out "ant init-forrest-entities" is now a prepreq for forrest to run properly, otherwise the XML doesn't validate because the entities can't resolve. most of hte core ant tasks take care of this via dependencies. a couple of notes about the specifics... a) i used the "specversion" since it's the most precise of our version numbers, it contains the datetime of dev builds, and is the number you would expect for official builds b) i tried to make the entity name consistent with the property name so that if someone smarter then me knows a way to get ant to dump all properties using a <filterchain> we can refer to any ant properties as entities not just solr.specversion c) if committed, Website_Update_HOWTO needs note about "ant init-forrest-entities" d) if committed, HowToRelease needs updated to indicate that the docs on the branch need regenerated/commited after building/testing the code sith specversion set , but before packaging.
        Hide
        Hoss Man added a comment -

        i could have sworn i clicked the other radio button

        Show
        Hoss Man added a comment - i could have sworn i clicked the other radio button
        Hide
        Yonik Seeley added a comment -

        "This document is for Apache Solr version 1.1.2007.05.29.11.45.13"
        That isn't the most user-friendly version string for between releases, but I guess it will serve.

        Show
        Yonik Seeley added a comment - "This document is for Apache Solr version 1.1.2007.05.29.11.45.13" That isn't the most user-friendly version string for between releases, but I guess it will serve.
        Hide
        Hoss Man added a comment -

        > "This document is for Apache Solr version 1.1.2007.05.29.11.45.13"
        > That isn't the most user-friendly version string for between releases, but I guess it will serve.

        Agreed, but "specversion" needs to be very explicit for the menifest file, and the only other version we have is "version" – which is just "X.Y-dev" between releases. We could add a new "versionordate" variable, but it's one more thing people would have to explicitly set when doing releases.

        Show
        Hoss Man added a comment - > "This document is for Apache Solr version 1.1.2007.05.29.11.45.13" > That isn't the most user-friendly version string for between releases, but I guess it will serve. Agreed, but "specversion" needs to be very explicit for the menifest file, and the only other version we have is "version" – which is just "X.Y-dev" between releases. We could add a new "versionordate" variable, but it's one more thing people would have to explicitly set when doing releases.
        Hide
        Yonik Seeley added a comment -

        I'm for committing this as-is, unless there are some other tweaks you want to make first.

        Show
        Yonik Seeley added a comment - I'm for committing this as-is, unless there are some other tweaks you want to make first.
        Hide
        Hoss Man added a comment -

        Committed revision 542626.

        Website_Update_HOWTO and HowToRelease updated to reflect the process tweaks.

        Show
        Hoss Man added a comment - Committed revision 542626. Website_Update_HOWTO and HowToRelease updated to reflect the process tweaks.

          People

          • Assignee:
            Hoss Man
            Reporter:
            Thorsten Scherler
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development