[Laszlo-dev] LzName to lz.name

[Lou Iorio]

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):
>
>
> dda at lester$ perl -spi.orig /tmp/moddoc1.pl /tmp/foo.txt /tmp/bar.txt
> dda at lester$ 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
> dda at lester$ diff /tmp/foo*
> 1c1
> < <xref linkend="XYZText"/> <xref linkend="InputText"/>
> ---
> > <sgmltag class="element" role="LzXYZText">LzXYZText</sgmltag>  
> <sgmltag class="element" role="LzInputText">LzInputText</sgmltag>
> dda at lester$ 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: dda at ddanderson.com
> www: http://www.ddanderson.com
>
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.openlaszlo.org/pipermail/laszlo-dev/attachments/20080907/bcd71b00/attachment.html