update all docs that explain sitemap fragments

• Key: FOR-922
• Type: Task
• Status: Open
• Priority: Major
• Assignee: Unassigned
• Reporter: David Crossley
• Component/s: Documentation and website
• Affects Version/s: 0.9-dev
• Fix Version/s: 0.9-dev

Description

There are various documents that explain parts of the sitemaps. Some of these mention pathnames, some have actual fragments of code copied from sitemaps. All of this needs to be updated to reflect the current sitemaps.

The sitemaps were recently updated to use locationmap, some sitemaps were simplified, filenames were changed, e.g. document2html.xsl to document-to-html.xsl

These changes need to be reflected in the current docs.

Comments

[David Crossley]

I used 'find and grep' to locate patterns "2.*\.xsl" and fixed them to the "*-to-*" convention (r436661).

Now remains the updating of xdocs that have sitemap snippets.

See also notes in FOR-546 - the sitemap-ref.html (and perhaps others) needs to also be updated regarding the use of plugins rather than everything in core sitemaps as it was when this doc was written.

[David Crossley]

We don't seem to be able to encourage someone to update these documents, so added a workaround to enable the 0.8 release ... a warning that they are out-of-date.

I used 'find and grep' to locate patterns "<map:" and investigated the docs. Some documents have generic snippets and so okay. Some are more explicit, so now have a warning. It is a pity because these are our main documents on the topic ...

sitemap-ref.xml
howto/howto-custom-html-source.xml
howto/forrest.xmap.html
howto/sitemap.xmap.html

[Chris Maloney]

If this is still considered open, I will try to do it. I've been studying Forrest and Cocoon a lot lately, and would like to lend a hand. I'd need somebody to help me get started, though.

[David Crossley]

Fantastic, thanks. What sort of help do you need to get started?

Are you comfortable with running forrest, and know that our docs are in $FORREST_HOME/site-author directory? Use head of our SVN trunk (i.e. 0.9-dev) and we concentrate on the top-level docs (site-author/content/xdocs) and the current dev version docs (site-author/content/xdocs/docs_0_90/) only.

I suggest that you provide a smallish patch to one of them, so we can ensure your patch technique before doing anything major.

Ask any general questions on the dev mail list. Thanks again.