[Bug documentation/11077] New: URLs in the HTML documentation are not meaningful

[Bug documentation/11077] New: URLs in the HTML documentation are not meaningful

[dmalcolm at redhat dot com]

Looking up information in the online documentation, I see URL fragments like 
this:
http://sourceware.org/systemtap/langref/node6.html#SECTION000612000000000000000

These URLs are not human-readable, and are fragile; they will change when new 
content is added above them in the source file.

The above URL would be better as something like:
http://sourceware.org/systemtap/langref/ProbePoints.html#PointerTypecasting

This would be human-readable, more robust in the face of editing, and be more 
likely to show up in search engines.

It looks like you're using DocBook to generate these docs.  I think you can fix 
this by adding "id" attributes to the relevant <section> tags.

-- 
           Summary: URLs in the HTML documentation are not meaningful
           Product: systemtap
           Version: unspecified
            Status: NEW
          Severity: normal
          Priority: P2
         Component: documentation
        AssignedTo: systemtap at sources dot redhat dot com
        ReportedBy: dmalcolm at redhat dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=11077

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug documentation/11077] URLs in the HTML documentation are not meaningful

[wcohen at redhat dot com]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1100 bytes --]


------- Additional Comments From wcohen at redhat dot com  2009-12-15 21:45 -------
This is being generated by latex2html from a latex file in doc/langref.tex
According to the man page for latex2html has the following option:

      -long_titles <num>
              Same  as  setting: $LONG_TITLES = <num>; Instead of the standard
              names: node1.html, node2.html,... the filenames  for  each  HTML
              page  are  constructed from the first <num> words of the section
              heading for that page, separated by the ‘_’  character.   Commas
              and  common  short words (a an to by of and for the) are omitted
              from both title and word-count.  Warning: Use this  switch  with
              great  caution.  Currently there are no checks for uniqueness of
              names or overall length. Very long names can easily result  from
              using this feature.


-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11077

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug documentation/11077] URLs in the HTML documentation are not meaningful

[wcohen at redhat dot com]

------- Additional Comments From wcohen at redhat dot com  2009-12-17 20:19 -------
Revise the generation of the documentation so that the files names are based on
the chapter names. However, the indices into the interior of the html files are
still rather cryptic labelling.  latex2html doesn't seem to have a way to
generate some more human friendly labels for the index.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11077

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug documentation/11077] URLs in the HTML documentation are not meaningful

[dmalcolm at redhat dot com]

------- Additional Comments From dmalcolm at redhat dot com  2009-12-17 20:30 -------
Yes, the URL in the initial description is now:
http://sourceware.org/systemtap/langref/Probe_points.html#SECTION0006120000000000
00000
an improvement, but not perfect yet, alas.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11077

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.