crossley 2002/07/10 22:26:58
Modified: src/documentation/xdocs/plan book.xml changes-doc.xml
doc.xml index.xml issues-doc.xml
Added: src/documentation/xdocs/plan linkstatus.xml
Log:
Added new document to describe various tools to assist with mending any
broken links.
Revision Changes Path
1.8 +1 -0 xml-cocoon2/src/documentation/xdocs/plan/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/plan/book.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- book.xml 4 Jul 2002 01:37:01 -0000 1.7
+++ book.xml 11 Jul 2002 05:26:58 -0000 1.8
@@ -18,6 +18,7 @@
<menu-item label="Changes" href="changes-doc.html"/>
<menu-item label="To Do" href="todo-doc.html"/>
<menu-item label="Issues" href="issues-doc.html"/>
+ <menu-item label="Fix broken links" href="linkstatus.html"/>
</menu>
<menu label="Other Planning">
1.18 +8 -1 xml-cocoon2/src/documentation/xdocs/plan/changes-doc.xml
Index: changes-doc.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/plan/changes-doc.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- changes-doc.xml 7 Jul 2002 07:10:33 -0000 1.17
+++ changes-doc.xml 11 Jul 2002 05:26:58 -0000 1.18
@@ -21,6 +21,13 @@
<release version="@version@" date="@date@">
<action dev="DC" type="add">
+ Encourage people to help with the mending broken links.
+ Added a
+ <link href="linkstatus.html">linkstatus</link> document describing some
+ tools.
+ </action>
+
+ <action dev="DC" type="add">
Added section to the
<link href="../mail-lists.html">Mailing Lists</link> document to describe
the new <code>cocoon-docs</code> mailing list.
1.7 +1 -1 xml-cocoon2/src/documentation/xdocs/plan/doc.xml
Index: doc.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/plan/doc.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- doc.xml 7 Jul 2002 07:10:33 -0000 1.6
+++ doc.xml 11 Jul 2002 05:26:58 -0000 1.7
@@ -25,7 +25,7 @@
<p>
Find out what documentation efforts are already in process among other users
and committers. First and foremost, join the
-<link href="../mail-lists.html"><code>cocoon-docs</code></link> mailing list.
+cocoon-docs <link href="../mail-lists.html">mailing list</link>.
</p>
</s2>
1.9 +2 -0 xml-cocoon2/src/documentation/xdocs/plan/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/plan/index.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- index.xml 7 Jul 2002 07:10:33 -0000 1.8
+++ index.xml 11 Jul 2002 05:26:58 -0000 1.9
@@ -55,6 +55,8 @@
<li><link href="changes-doc.html">Documentation History of Changes</link></li>
<li><link href="todo-doc.html">Documentation To Do List</link></li>
<li><link href="issues-doc.html">Documentation Issues</link></li>
+ <li><link href="linkstatus.html">Linkstatus</link>
+ - Tools to assess and mend any broken hyperlinks</li>
</ul>
<ul>
1.2 +9 -7 xml-cocoon2/src/documentation/xdocs/plan/issues-doc.xml
Index: issues-doc.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/plan/issues-doc.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- issues-doc.xml 4 Jul 2002 01:32:19 -0000 1.1
+++ issues-doc.xml 11 Jul 2002 05:26:58 -0000 1.2
@@ -16,8 +16,11 @@
<s1 title="Issues">
<p>
-Certain issues need to be addressed for all current and future
-documentation. Please note that many of these issues are being addressed or
discussed on the Apache <link href="http://xml.apache.org/forrest/";>Forrest</link>
Project.
+Certain issues need to be addressed for all current and future documentation.
+Many of these issues are being addressed and discussed on the
+cocoon-docs <link href="../mail-lists.html">mailing list</link>.
+Documentation infrastructure issues are also addressed on the Apache
+<link href="http://xml.apache.org/forrest/";>Forrest</link> Project.
</p>
<ul>
@@ -36,11 +39,10 @@
</li>
<li>
-The excellent LinkAlarm service is used after each major public release
-of Cocoon to help discover any broken external links. (Internal links
-are evaluated during the docs build.) Please see the README file at <link
href="linkalarm-readme.txt">linkalarm-readme.txt</link>
-and help to attend to any issues. However, the site is updated more
-frequently now, so the cost of using LinkAlarm may not be wise. We need to take
advantage of the capabilities of Cocoon's LinkStatus Generator. Perhaps this can be
incorporated into a custom build target for docs.
+Cocoon has various tools to assist with monitoring broken hyperlinks.
+There is a separate document to explain the
+<link href="linkstatus.html">linkstatus</link> and show how you can help to
+ensure robustness of the documentation set and the website.
</li>
<li>
1.1 xml-cocoon2/src/documentation/xdocs/plan/linkstatus.xml
Index: linkstatus.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>Linkstatus - assess and mend any broken hyperlinks</title>
<subtitle>Overview</subtitle>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
Cocoon has various tools to ensure the internal links. However, there will
still be occasional problems. Please help to keep it robust.
</p>
<p>
External links are a bit trickier. It is not really fair to banish them just
because they were not accessible on the day that a link verification was run.
Actually the external link situation is going to become an
issue, now that we have accepted a whole section of
<link href="../link/index.html">Cocoon Links</link>
docs devoted to external resources.
</p>
<p>
Robust internal links is the main issue. However, how far
do we go down the road of external link management? Please help to develop
automated solutions.
</p>
</s1>
<s1 title="Assessment tools">
<s2 title="build docs">
<p>
Please do "build docs" before creating or committing a patch. The build will
fail on internal breaks. (Not sure about links to and within Javadocs.)
</p>
</s2>
<s2 title="LinkStatus Generator">
<p>
This Cocoon Sample will start at the home page of the local documentation
webapp and traverse each internal link, reporting its status in a colour-coded
table.
</p>
<p>
See <link href="../../overview.html#samples">Cocoon Samples</link> in your
local webapp distribution via
<code>http://localhost:8080/cocoon/samples/linkstatus/</code>
</p>
</s2>
<s2 title="LinkAlarm web service">
<note>We cannot rely on using the LinkAlarm service (a fee-based professional
service). We need to develop our own capability.
</note>
<p>
The excellent LinkAlarm service is used after each public release of Cocoon
to help discover any broken external links on the final website.
Please see the README file at
<link href="linkalarm-readme.txt">linkalarm-readme.txt</link>
and help to attend to any issues.
</p>
<p>
The LinkAlarm service traverses the Cocoon website occasionally. The full
set of reports are at
<link
href="http://reports.linkalarm.com/373104199608/";>http://reports.linkalarm.com/373104199608/</link>
</p>
<p>
There is a new webapp sample that retrieves the summary report
<code>links.broken.txt</code> and pretty-prints the list.
See <link href="../../overview.html#samples">Cocoon Samples</link> in your
local webapp distribution via
<code>http://localhost:8080/cocoon/samples/linkstatus/</code>
</p>
</s2>
</s1>
<s1 title="Further development">
<p>
We need to take more advantage of the capabilities of Cocoon's LinkStatus
Generator. Perhaps this can be incorporated into a custom build target for
docs.
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
