On Sep 3, 2008, at 10:13 AM, Donald Anderson wrote:
Hi Lou.
I didn't even know about sgmltag. I was aware of xref and link,
ulink, olink.
I'm a bit hesitant to change file names - I guess I just don't know
about how the output file names are chosen and tracked.
But there are only 55 files in question, somehow that makes it seem
easier.
Anyway, let's look at the options you propose:
On Sep 3, 2008, at 8:42 AM, Lou Iorio wrote:
Hi Don,
I'm looking at LPP-6904: reference: make sure classes and tags are
up to date, e.g., lz.text instead of LzText
This is starting to look like a huge task, since we don't seem to
have any one standard when it
comes to linking from one reference page to another. For example:
trunk/WEB-INF/lps/lfc/data/LzDatapath.lzs
links to other pages in at least two ways:
<xref linkend="LzLazyReplicationManager" />
and
<sgmltag class="element" role="LzInputText">LzInputText</sgmltag>
The second builds the HTML link from the role attribute, and the
page it's
referring to is called LzInputText.html. The only problem with this
is that I can't just
change instances of LzInputText to lz.inputtext, since that would
result in broken
links all over the place.
Using an xref seems to me to be a better way, because then I could
just change
<sgmltag class="element" role="LzInputText">LzInputText</sgmltag>
to
<xref linkend="LzInputText" />
since that should result in the right link and the right text in
the HTML.
My first impulse is to change all sgmltags to xrefs. That assumes
that all
generated HTML files have anchors that follow this form
I would assume that anchors are generated in xsl scripts, so they
should all have them.
, and I don't know
if sgmltags serve any other purpose.
You got me!
I'm reluctant to change them then, since I don't know if the <sgmltag>
tag is used for anything
else.
Anyway xrefs seem very good - they are certainly easy to read and
maintain.
Another approach would be to change the HTML file naming convention
to match
the tag or class name, for example changing
LzInputText.html to lz.inputtext.html
The second way would make a global search and replace more
feasible, but of course,
it's a lot more work for you.
I think much less work for me would be to write a perl script to mod
the files.
As I understand it, any approach needs to modify anything like this:
<sgmltag class="element" role="LzXXXX">LzXXXX</sgmltag>
Do we know that LzXXXX is the same?
(i.e. if they are different, which is more reliable?)
I would guess "role" is the more reliable.
Anyway, here's a simple perl script that should convert sgmltags to
xref (using the 'role')
#!/usr/bin/perl -sni.orig
s:<sgmltag class="element" role="Lz([a-zA-Z0-9]*)">Lz([a-zA-Z0-9]*)</
sgmltag>:<xref linkend="\1"/>:g;
Actually, I can do this search and replace directly in BBEdit, which
is easier since is has multi-file
search, and I really need to verify every change. For example, this
strategy would change LzDelegate, which
we don't want to do.
Also, we need to keep the Lz part, so it's
s:<sgmltag class="element" role="(Lz[a-zA-Z0-9]*)">Lz([a-zA-Z0-9]*)</
sgmltag>:<xref linkend="\1"/>:g;
Put that in /tmp/moddoc1.pl
And run 'perl -spi.orig /tmp/moddoc1.pl' on your files -- it will
create *.orig files (even for files
you didn't modify, unfortunately):
[EMAIL PROTECTED] perl -spi.orig /tmp/moddoc1.pl /tmp/foo.txt /tmp/bar.txt
[EMAIL PROTECTED] ls -l /tmp/foo* /tmp/bar*
-rw-r--r-- 1 dda wheel 47 Sep 3 10:08 /tmp/bar.txt
-rw-r--r-- 1 dda wheel 114 Sep 3 10:08 /tmp/bar.txt.orig
-rw-r--r-- 1 dda wheel 54 Sep 3 10:08 /tmp/foo.txt
-rw-r--r-- 1 dda wheel 128 Sep 3 09:57 /tmp/foo.txt.orig
[EMAIL PROTECTED] diff /tmp/foo*
1c1
< <xref linkend="XYZText"/> <xref linkend="InputText"/>
---
> <sgmltag class="element" role="LzXYZText">LzXYZText</sgmltag>
<sgmltag class="element" role="LzInputText">LzInputText</sgmltag>
[EMAIL PROTECTED] diff /tmp/bar*
1,2c1,2
< <xref linkend="Bar"/>
< <xref linkend="Tavern"/>
---
> <sgmltag class="element" role="LzBar">LzBA</sgmltag>
> <sgmltag class="element" role="LzTavern">LzTaberno</sgmltag>
Does that do the trick?
It only solves a small part of the problem, since a class name may be
inside a <code> or
<literal> tag, and it might have no markup at all (or markup I don't
know about). Also, the reference
may be to a class method, like LzClass.method().
It would be much easier if the file names matched the class and tag
names, for example,
lz.BrowserService would be in lz.BrowserService.html instead of
LzBrowserService.html.
I'm not clever enough to figure out how the file names are
constructed, but I suspect it's part
of the JS2Doc process (JS2Doc.java perhaps?). Also, whatever is
generating, for example, this:
<div class="refentry" lang="en"><a name="LzBrowserService"></a><div
class="titlepage"></div>
in the HTML would need to change.
This change would make a global search and replace possible, and
wouldn't break any
links. Without this change, I need to go through all the .lzs and .lzx
files and deal with each
occurrence of Lz[a-zA-Z0-9] one at a time. I suspect this process
would take weeks, and
be highly error prone, but I also have no idea how much work it is to
change the file names
and ids.
Lou
A more search and replace based strategy would help to solve
another problem, that of the
class and tag names in the source code that are not marked up at
all, but just inline text,
like this from lz.datapath:
"When a node is replicated, an LzReplicationManager takes its
place..."
With the current scheme, it seems I have to search the source code
for every instance
of Lz[A-Z] and deal with them one at a time. I can't even hazard a
guess as to how long
that would take.
If there's another approach I haven't thought of (which is almost
certainly the case), I'd appreciate
any advice.
thanks,
Lou
--
Don Anderson
Java/C/C++, Berkeley DB, systems consultant
voice: 617-547-7881
email: [EMAIL PROTECTED]
www: http://www.ddanderson.com
