Details
-
Bug
-
Status: Closed
-
Major
-
Resolution: Fixed
-
0.7, 0.8
-
None
Description
Working through the docs, I found a few bugs. Fixing these will be especially helpful to beginners who are trying to align instructions and reality. Unless stated otherwise, the bugs below apply to both the v0.7 docs and the v0.8dev docs even if the URL is for v0.7.
1. [docs, message when running "forrest seed", forrest.properties] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": The message that is displayed when running "forrest seed" lists src/documentation/resources/images as one of the generated directories, but this directory does not exist. Instead, there is a src/documentation/content/xdocs/images directory.
Further, the forrest.properties file generated when running "forrest seed" has this comment line:
#project.images-dir=${project.resources-dir}/images
to document the default value used by forrest, but this directory does not exist. Strangely, $FORREST_HOME/main/webapp/default-forrest.properties contains:
project.images-dir=${project.resources-dir}/images
Is there yet another place where project.images-dir is ultimately set to ${project.xdocs-dir}/images?
2. [docs, message when running "forrest seed"] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": I think the line that says:
/src/documentation/content/xdocs # Site content.
should read:
/src/documentation/content # Site content.
(There already is a line for "XML content".)
3. [docs, message when running "forrest seed", forrest.properties] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": Running "forrest seed" no longer generates a "status.xml" file.
4. [docs] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": The output of "tree" given differs slightly from the set of files actually created when running "forrest seed".
5. [docs] http://forrest.apache.org/docs_0_70/your-project.html: In the "tabs.xml" section, the two-level tab example is nonsensical because the href attribute value of the first-level tab is an external URL: The second-level tabs are never displayed.
6. [docs] http://forrest.apache.org/docs_0_70/howto/forrest.xmap.html: The first section heading should be "forrest.xmap" instead of "sitemap.xmap".
7. [docs] http://forrest.apache.org/docs_0_70/howto/howto-custom-html-source.html: There is a formatting bug in the last sitemap snippet (bottom of the page): The <strong> markup should not be inside the <pre> section, it shows up verbatim.
8. [docs] http://forrest.apache.org/docs_0_70/howto/howto-custom-html-source.html: On the same line that has bug (7), the {forrest:stylesheets} variable should be {project:resources.stylesheets}.
9. [docs] http://forrest.apache.org/dtdx/document-v20.html: In the "Using sections" section, it still says that the section title is an attribute of the <section> element, but in document-v20, the title is a child element.
10. [docs] http://forrest.apache.org/docs_0_70/linking.html: In the "Indirect linking" section, the displayed URL should be "http://xml.apache.org/commons/components/resolver/" instead of "http://xml.apache.org/components/resolver/". Note: The href attribute is correct.
11. [docs] http://forrest.apache.org/docs_0_70/forrest-contract.html: In the "TheProject must:" section, in the third bullet, the {projecthome} variable should be {docroot}.
12. [docs] http://forrest.apache.org/docs_0_70/howto/howto-howto.html: In the "Prerequisites" section, the "DTD documentation" link in the note box should point to the howto-v20 DTD instead of the howto-v13 DTD. [This one is already fixed in v0.8dev.]
13. [docs] http://forrest.apache.org/tools/forrestbot.html: In the "Workstage Properties" section, the default value for build.work-dir is listed as "work", but it's actually "work/${ant.project.name}" (see tools/forrestbot/core/build.xml, line 20).
14. [docs] http://forrest.apache.org/tools/forrestbot.html: In the "Workstage Properties" section, the description for property "deploy.local.dir" says that relative paths will be relative to ${bot.home}, but they are actually relative to ${basedir}.
1. [docs, message when running "forrest seed", forrest.properties] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": The message that is displayed when running "forrest seed" lists src/documentation/resources/images as one of the generated directories, but this directory does not exist. Instead, there is a src/documentation/content/xdocs/images directory.
Further, the forrest.properties file generated when running "forrest seed" has this comment line:
#project.images-dir=${project.resources-dir}/images
to document the default value used by forrest, but this directory does not exist. Strangely, $FORREST_HOME/main/webapp/default-forrest.properties contains:
project.images-dir=${project.resources-dir}/images
Is there yet another place where project.images-dir is ultimately set to ${project.xdocs-dir}/images?
2. [docs, message when running "forrest seed"] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": I think the line that says:
/src/documentation/content/xdocs # Site content.
should read:
/src/documentation/content # Site content.
(There already is a line for "XML content".)
3. [docs, message when running "forrest seed", forrest.properties] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": Running "forrest seed" no longer generates a "status.xml" file.
4. [docs] http://forrest.apache.org/docs_0_70/your-project.html, section "Seeding a new project": The output of "tree" given differs slightly from the set of files actually created when running "forrest seed".
5. [docs] http://forrest.apache.org/docs_0_70/your-project.html: In the "tabs.xml" section, the two-level tab example is nonsensical because the href attribute value of the first-level tab is an external URL: The second-level tabs are never displayed.
6. [docs] http://forrest.apache.org/docs_0_70/howto/forrest.xmap.html: The first section heading should be "forrest.xmap" instead of "sitemap.xmap".
7. [docs] http://forrest.apache.org/docs_0_70/howto/howto-custom-html-source.html: There is a formatting bug in the last sitemap snippet (bottom of the page): The <strong> markup should not be inside the <pre> section, it shows up verbatim.
8. [docs] http://forrest.apache.org/docs_0_70/howto/howto-custom-html-source.html: On the same line that has bug (7), the {forrest:stylesheets} variable should be {project:resources.stylesheets}.
9. [docs] http://forrest.apache.org/dtdx/document-v20.html: In the "Using sections" section, it still says that the section title is an attribute of the <section> element, but in document-v20, the title is a child element.
10. [docs] http://forrest.apache.org/docs_0_70/linking.html: In the "Indirect linking" section, the displayed URL should be "http://xml.apache.org/commons/components/resolver/" instead of "http://xml.apache.org/components/resolver/". Note: The href attribute is correct.
11. [docs] http://forrest.apache.org/docs_0_70/forrest-contract.html: In the "TheProject must:" section, in the third bullet, the {projecthome} variable should be {docroot}.
12. [docs] http://forrest.apache.org/docs_0_70/howto/howto-howto.html: In the "Prerequisites" section, the "DTD documentation" link in the note box should point to the howto-v20 DTD instead of the howto-v13 DTD. [This one is already fixed in v0.8dev.]
13. [docs] http://forrest.apache.org/tools/forrestbot.html: In the "Workstage Properties" section, the default value for build.work-dir is listed as "work", but it's actually "work/${ant.project.name}" (see tools/forrestbot/core/build.xml, line 20).
14. [docs] http://forrest.apache.org/tools/forrestbot.html: In the "Workstage Properties" section, the description for property "deploy.local.dir" says that relative paths will be relative to ${bot.home}, but they are actually relative to ${basedir}.