forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David Crossley (JIRA)" <j...@apache.org>
Subject [jira] Closed: (FOR-751) Various documentation bugs
Date Mon, 05 Dec 2005 04:55:31 GMT
     [ http://issues.apache.org/jira/browse/FOR-751?page=all ]
     
David Crossley closed FOR-751:
------------------------------

    Fix Version: 0.8-dev
     Resolution: Fixed
      Assign To:     (was: David Crossley)

Thanks. I applied your suggested changes, but only to the 0.8-dev docs.

We already knew that many docs need review. Especially your-project.html needs a complete
review. However it is still good to add your tweaks, thanks. It is better if you can send
a patch to the xml source documents (easier for the committers).

Regarding item #1 ... in recent versions of Forrest, the resources/images/ directory is the
main location for the project images. The old directory xdocs/images/ probably still works,
but is not recommended. There are more places in the docs where that needs to change.

Item #5 is not yet done. Moved it to an issue of its own (FOR-753). Someone nees to provide
a patch.

> Various documentation bugs
> --------------------------
>
>          Key: FOR-751
>          URL: http://issues.apache.org/jira/browse/FOR-751
>      Project: Forrest
>         Type: Bug
>   Components: Documentation and website
>     Versions: 0.7, 0.8-dev
>     Reporter: Richard Calmbach
>      Fix For: 0.8-dev

>
> 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}.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
   http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
   http://www.atlassian.com/software/jira


Mime
View raw message