You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Jonathan <ja...@i-2000.com> on 2001/06/17 23:57:45 UTC
The documentation, xml, and stylesheets
Yea, but now I will have to learn the dtd and create complex stylesheets.
Gentlemen. if I may be frank, this is an excercise in technical
masturbation. If I ever want to redo it all.....than I will. Stylesheets do
not help, and those that have had to use them know exactly what I am talking
about.
----- Original Message -----
From: "Ted Husted" <hu...@apache.org>
To: <st...@jakarta.apache.org>
Sent: Sunday, June 17, 2001 6:05 AM
Subject: Re: I would like to offer myself to help with documentation
> Jonathan wrote:
> > It would be nice if it was just simple. Stylesheets are not. Why dont
we
> > just use html
>
> Half the time, I think just to make my life more difficult ;-)
>
> The other half, I think so that we can
>
> * Ensure formatting consistency,
> * Change the look without editing the content,
> * Generate navigational constructs (though we could use more of this),
> * and, practice what we preach.
>
> Most, if not all, of the Jakarta sub-project Web sites are based on XML.
>
> Personally, I believe there's a desperate need for more XML editing
> tools. Everyone please keep posting any XML links you find here, and
> I'll start a list.
>
>
> -- Ted Husted, Husted dot Com, Fairport NY USA.
> -- Custom Software ~ Technical Services.
> -- Tel 716 737-3463.
> -- http://www.husted.com/about/struts/
>
Re: The documentation, xml, and stylesheets
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Mon, 18 Jun 2001, Barry Glasco wrote:
> You are a Jack Ass! That is the most technical way
> I could think of putting it.
>
Disagreements over technologies need not devolve into personal
attacks. One of the refreshing things about the Struts community has been
the relative absence of stuff like this. Let's keep it that way, and
avoid this kind of comment on the mailing lists.
Craig
Re: The documentation, xml, and stylesheets
Posted by Barry Glasco <bg...@silverhosting.com>.
You are a Jack Ass! That is the most technical way
I could think of putting it.
Later
----- Original Message -----
From: "Michael Westbay" <we...@seaple.icc.ne.jp>
To: <st...@jakarta.apache.org>
Sent: Monday, June 18, 2001 8:27 PM
Subject: Re: The documentation, xml, and stylesheets
> Asbell-san wrote:
>
> > Mike, I am forced to work with xslt every day, [...]
>
> It sounds to me like you're one of those many people who majored in
something
> that had nothing to do with computers, then found yourself in the IT
field.
> I was a Computer Science major. I taught myself HTML, XML, SGML, XSL, and
> the rest of the alphabet soup in my own time after work simply because I
> found them fascinating.
>
> > [...] and each day I find a new
> > reason to say "what in the WORLD do people see in this?!". It has its
> > place in changing from schema to schema, but who want to get so deep
into a
> > technology which is very hard to control, and in complex schemas
consumes
> > more effort than it is worth to get what you want out of it.
>
> Let me venture another guess. You're working primarily with poorly
> documented and or thought out DTDs that are ever changing as more
> functionality is desired, leaving you to constantly update the style sheet
> transforms to satisfy the whims of your boss.
>
> First of all, getting in deep with the technology gives one a better
> understanding of it. I started learning HTML in 1995 armed with Mosaic
and
> my trusty vi editor. GUIs are nice, but IMHO, they separate the creator
from
> the underlying technologies too much. I'd rather know what's going on
under
> the hood. Why does a page render the way it does. Getting a good
> fundamental knowledge of the low level technologies allows me to spot and
fix
> problems quickly. It also allows for better efficiency when using the
> technologies.
>
> With a better understanding, the technologies are not hard to control. A
> well written schema, even a very complex one (like DocBook) is well worth
the
> effort of getting a good understanding of the underlying technologies.
>
> As Winterfeldt-san pointed out, the whole XML/XSL bit it may be overkill
for
> a few scattered unrelated documents. But when the documentation starts
> increasing, a well thought out schema for allowing flexible access to what
> would be a mountian load of dead trees saves a great deal in the long run.
>
> I don't know if my evengilism of a technology can change your mind. We
> obviously have very different backgrounds (I was the only one in my
English
> classes to turn in papers written in LaTeX [edited in vi, of course] -
> everyone else used WordPerfect or [gasp!] a typewriter). And our jobs
seem
> to give different levels of satisfaction: I'd study this stuff on my own
if
> I didn't get to work with it anyway, whereas you're "forced to work with
xslt
> every day."
>
> I think it's great that you're volunteering to help with the
documentation.
> But I also think it's strange that you hadn't gone through what is there
and
> seen how it is generated from XML via XSLT. I would have expected some
sort
> of professional curiosity as to how others deal with documentation issues,
> since that seems to be your line of work. But then, maybe it's me
applying
> my own drive to learn more ways of doing things to improve my own skills
and
> the way I do my job. (Sorry, I forget sometimes that not everyone takes a
> job in the tech field by choice.)
>
> --
> Michael Westbay
> Work: Beacon-IT http://www.beacon-it.co.jp/
> Home: http://www.seaple.icc.ne.jp/~westbay
> Commentary: http://www.japanesebaseball.com/
>
>
Re: The documentation, xml, and stylesheets
Posted by Jonathan Asbell <ja...@i-2000.com>.
I am at a loss as to how to respond to this.....
You obviously work alone
----- Original Message -----
From: "Michael Westbay" <we...@seaple.icc.ne.jp>
To: <st...@jakarta.apache.org>
Sent: Monday, June 18, 2001 8:27 PM
Subject: Re: The documentation, xml, and stylesheets
> Asbell-san wrote:
>
> > Mike, I am forced to work with xslt every day, [...]
>
> It sounds to me like you're one of those many people who majored in
something
> that had nothing to do with computers, then found yourself in the IT
field.
> I was a Computer Science major. I taught myself HTML, XML, SGML, XSL, and
> the rest of the alphabet soup in my own time after work simply because I
> found them fascinating.
>
> > [...] and each day I find a new
> > reason to say "what in the WORLD do people see in this?!". It has its
> > place in changing from schema to schema, but who want to get so deep
into a
> > technology which is very hard to control, and in complex schemas
consumes
> > more effort than it is worth to get what you want out of it.
>
> Let me venture another guess. You're working primarily with poorly
> documented and or thought out DTDs that are ever changing as more
> functionality is desired, leaving you to constantly update the style sheet
> transforms to satisfy the whims of your boss.
>
> First of all, getting in deep with the technology gives one a better
> understanding of it. I started learning HTML in 1995 armed with Mosaic
and
> my trusty vi editor. GUIs are nice, but IMHO, they separate the creator
from
> the underlying technologies too much. I'd rather know what's going on
under
> the hood. Why does a page render the way it does. Getting a good
> fundamental knowledge of the low level technologies allows me to spot and
fix
> problems quickly. It also allows for better efficiency when using the
> technologies.
>
> With a better understanding, the technologies are not hard to control. A
> well written schema, even a very complex one (like DocBook) is well worth
the
> effort of getting a good understanding of the underlying technologies.
>
> As Winterfeldt-san pointed out, the whole XML/XSL bit it may be overkill
for
> a few scattered unrelated documents. But when the documentation starts
> increasing, a well thought out schema for allowing flexible access to what
> would be a mountian load of dead trees saves a great deal in the long run.
>
> I don't know if my evengilism of a technology can change your mind. We
> obviously have very different backgrounds (I was the only one in my
English
> classes to turn in papers written in LaTeX [edited in vi, of course] -
> everyone else used WordPerfect or [gasp!] a typewriter). And our jobs
seem
> to give different levels of satisfaction: I'd study this stuff on my own
if
> I didn't get to work with it anyway, whereas you're "forced to work with
xslt
> every day."
>
> I think it's great that you're volunteering to help with the
documentation.
> But I also think it's strange that you hadn't gone through what is there
and
> seen how it is generated from XML via XSLT. I would have expected some
sort
> of professional curiosity as to how others deal with documentation issues,
> since that seems to be your line of work. But then, maybe it's me
applying
> my own drive to learn more ways of doing things to improve my own skills
and
> the way I do my job. (Sorry, I forget sometimes that not everyone takes a
> job in the tech field by choice.)
>
> --
> Michael Westbay
> Work: Beacon-IT http://www.beacon-it.co.jp/
> Home: http://www.seaple.icc.ne.jp/~westbay
> Commentary: http://www.japanesebaseball.com/
>
Re: The documentation, xml, and stylesheets
Posted by Michael Westbay <we...@seaple.icc.ne.jp>.
Asbell-san wrote:
> Mike, I am forced to work with xslt every day, [...]
It sounds to me like you're one of those many people who majored in something
that had nothing to do with computers, then found yourself in the IT field.
I was a Computer Science major. I taught myself HTML, XML, SGML, XSL, and
the rest of the alphabet soup in my own time after work simply because I
found them fascinating.
> [...] and each day I find a new
> reason to say "what in the WORLD do people see in this?!". It has its
> place in changing from schema to schema, but who want to get so deep into a
> technology which is very hard to control, and in complex schemas consumes
> more effort than it is worth to get what you want out of it.
Let me venture another guess. You're working primarily with poorly
documented and or thought out DTDs that are ever changing as more
functionality is desired, leaving you to constantly update the style sheet
transforms to satisfy the whims of your boss.
First of all, getting in deep with the technology gives one a better
understanding of it. I started learning HTML in 1995 armed with Mosaic and
my trusty vi editor. GUIs are nice, but IMHO, they separate the creator from
the underlying technologies too much. I'd rather know what's going on under
the hood. Why does a page render the way it does. Getting a good
fundamental knowledge of the low level technologies allows me to spot and fix
problems quickly. It also allows for better efficiency when using the
technologies.
With a better understanding, the technologies are not hard to control. A
well written schema, even a very complex one (like DocBook) is well worth the
effort of getting a good understanding of the underlying technologies.
As Winterfeldt-san pointed out, the whole XML/XSL bit it may be overkill for
a few scattered unrelated documents. But when the documentation starts
increasing, a well thought out schema for allowing flexible access to what
would be a mountian load of dead trees saves a great deal in the long run.
I don't know if my evengilism of a technology can change your mind. We
obviously have very different backgrounds (I was the only one in my English
classes to turn in papers written in LaTeX [edited in vi, of course] -
everyone else used WordPerfect or [gasp!] a typewriter). And our jobs seem
to give different levels of satisfaction: I'd study this stuff on my own if
I didn't get to work with it anyway, whereas you're "forced to work with xslt
every day."
I think it's great that you're volunteering to help with the documentation.
But I also think it's strange that you hadn't gone through what is there and
seen how it is generated from XML via XSLT. I would have expected some sort
of professional curiosity as to how others deal with documentation issues,
since that seems to be your line of work. But then, maybe it's me applying
my own drive to learn more ways of doing things to improve my own skills and
the way I do my job. (Sorry, I forget sometimes that not everyone takes a
job in the tech field by choice.)
--
Michael Westbay
Work: Beacon-IT http://www.beacon-it.co.jp/
Home: http://www.seaple.icc.ne.jp/~westbay
Commentary: http://www.japanesebaseball.com/
Re: The documentation, xml, and stylesheets
Posted by David Winterfeldt <dw...@yahoo.com>.
I think it is a matter of planning for the future.
Changing 10 pages of HTML may not be a big deal or
even a hundred, but as the site's documentation keeps
expanding it's easier to keep the documentation in XML
so Struts and other Jakarta projects can easily be
reformatted and released with a new look and feel with
minimal effort. Maybe there will be a version of the
site for hand held devices one day. With everything
in XML it would be feasible to do something like this.
I would just work on it in plain text as Ted
suggested so you can get something together without
being distracted and then worry about adding the tags.
David
--- Jonathan Asbell <ja...@i-2000.com> wrote:
> Mike, I am forced to work with xslt every day, and
> each day I find a new
> reason to say "what in the WORLD do people see in
> this?!". It has its place
> in changing from schema to scema, but who want to
> get so deep into a
> technology which is very hard to control, and in
> complex schemas consumes
> more effort than it is worth to get what you want
> out of it.
>
> ----- Original Message -----
> From: "Michael Westbay" <we...@seaple.icc.ne.jp>
> To: <st...@jakarta.apache.org>
> Sent: Sunday, June 17, 2001 7:45 PM
> Subject: Re: The documentation, xml, and stylesheets
>
>
> > Jonathan-san wrote:
> >
> > > Yea, but now I will have to learn the dtd and
> create complex
> stylesheets.
> > > Gentlemen. if I may be frank, this is an
> excercise in technical
> > > masturbation. If I ever want to redo it
> all.....than I will.
> Stylesheets
> > > do not help, and those that have had to use them
> know exactly what I am
> > > talking about.
> >
> > I use them. And the more I use them, the more I
> like them. Just look at
> the
> > power behind the current Struts' documentation
> xml, namely DTD and the
> user
> > manuals for the tags get generated from a single
> XML file. The next
> logical
> > step is to have that XML file generated from
> JavaDoc, so that if the
> > specification of a tag changes, the change can
> easily be reflected in the
> DTD
> > and manual without having to edit external
> documents.
> >
> > I'm currently looking at the idea of creating
> pages in XML that generate
> JSP
> > pages (with Struts tags among others) and help
> HTML files. The help files
> > can also be processed with FOP for a PDF manual.
> One source, multiple
> > integrated, cross referenced outputs.
> >
> > No, it isn't easy. But for building a complex
> system where source and
> > documentation may be managed together, it's a very
> powerful tool.
> >
> > MS Word attachments and mail in HTML format (70%
> of the spam I recieve)
> get
> > filtered to /dev/null. I won't touch them. (Why
> does Outlook's HTML
> > messages take up to 32 times the plain text size?)
> In fact, lot of
> messages
> > got filtered the past couple of weeks since. Even
> though most of you have
> > HTML mail turned off, Outlook assumes that when
> replying to an HTML
> message,
> > you want to send in HTML format, too. Judging
> form the headers in my spam
> > log, I belive that Mozilla is equally guilty, so
> I'm not just picking on
> MS.
> >
> > Should proper mail netiquitte be included on the
> mail subscription page?
> The
> > FAQ that comes periodically in the DocBook mailing
> list spells out proper
> > quoting technique (snip-quote-reply) rather
> nicely, and establishes
> policies
> > for attachments and cross posting.
> >
> > --
> > Michael Westbay
> > Work: Beacon-IT http://www.beacon-it.co.jp/
> > Home:
> http://www.seaple.icc.ne.jp/~westbay
> > Commentary: http://www.japanesebaseball.com/
> >
>
__________________________________________________
Do You Yahoo!?
Spot the hottest trends in music, movies, and more.
http://buzz.yahoo.com/
Re: The documentation, xml, and stylesheets
Posted by Jonathan Asbell <ja...@i-2000.com>.
Mike, I am forced to work with xslt every day, and each day I find a new
reason to say "what in the WORLD do people see in this?!". It has its place
in changing from schema to scema, but who want to get so deep into a
technology which is very hard to control, and in complex schemas consumes
more effort than it is worth to get what you want out of it.
----- Original Message -----
From: "Michael Westbay" <we...@seaple.icc.ne.jp>
To: <st...@jakarta.apache.org>
Sent: Sunday, June 17, 2001 7:45 PM
Subject: Re: The documentation, xml, and stylesheets
> Jonathan-san wrote:
>
> > Yea, but now I will have to learn the dtd and create complex
stylesheets.
> > Gentlemen. if I may be frank, this is an excercise in technical
> > masturbation. If I ever want to redo it all.....than I will.
Stylesheets
> > do not help, and those that have had to use them know exactly what I am
> > talking about.
>
> I use them. And the more I use them, the more I like them. Just look at
the
> power behind the current Struts' documentation xml, namely DTD and the
user
> manuals for the tags get generated from a single XML file. The next
logical
> step is to have that XML file generated from JavaDoc, so that if the
> specification of a tag changes, the change can easily be reflected in the
DTD
> and manual without having to edit external documents.
>
> I'm currently looking at the idea of creating pages in XML that generate
JSP
> pages (with Struts tags among others) and help HTML files. The help files
> can also be processed with FOP for a PDF manual. One source, multiple
> integrated, cross referenced outputs.
>
> No, it isn't easy. But for building a complex system where source and
> documentation may be managed together, it's a very powerful tool.
>
> MS Word attachments and mail in HTML format (70% of the spam I recieve)
get
> filtered to /dev/null. I won't touch them. (Why does Outlook's HTML
> messages take up to 32 times the plain text size?) In fact, lot of
messages
> got filtered the past couple of weeks since. Even though most of you have
> HTML mail turned off, Outlook assumes that when replying to an HTML
message,
> you want to send in HTML format, too. Judging form the headers in my spam
> log, I belive that Mozilla is equally guilty, so I'm not just picking on
MS.
>
> Should proper mail netiquitte be included on the mail subscription page?
The
> FAQ that comes periodically in the DocBook mailing list spells out proper
> quoting technique (snip-quote-reply) rather nicely, and establishes
policies
> for attachments and cross posting.
>
> --
> Michael Westbay
> Work: Beacon-IT http://www.beacon-it.co.jp/
> Home: http://www.seaple.icc.ne.jp/~westbay
> Commentary: http://www.japanesebaseball.com/
>
Re: The documentation, xml, and stylesheets
Posted by Michael Westbay <we...@seaple.icc.ne.jp>.
Jonathan-san wrote:
> Yea, but now I will have to learn the dtd and create complex stylesheets.
> Gentlemen. if I may be frank, this is an excercise in technical
> masturbation. If I ever want to redo it all.....than I will. Stylesheets
> do not help, and those that have had to use them know exactly what I am
> talking about.
I use them. And the more I use them, the more I like them. Just look at the
power behind the current Struts' documentation xml, namely DTD and the user
manuals for the tags get generated from a single XML file. The next logical
step is to have that XML file generated from JavaDoc, so that if the
specification of a tag changes, the change can easily be reflected in the DTD
and manual without having to edit external documents.
I'm currently looking at the idea of creating pages in XML that generate JSP
pages (with Struts tags among others) and help HTML files. The help files
can also be processed with FOP for a PDF manual. One source, multiple
integrated, cross referenced outputs.
No, it isn't easy. But for building a complex system where source and
documentation may be managed together, it's a very powerful tool.
MS Word attachments and mail in HTML format (70% of the spam I recieve) get
filtered to /dev/null. I won't touch them. (Why does Outlook's HTML
messages take up to 32 times the plain text size?) In fact, lot of messages
got filtered the past couple of weeks since. Even though most of you have
HTML mail turned off, Outlook assumes that when replying to an HTML message,
you want to send in HTML format, too. Judging form the headers in my spam
log, I belive that Mozilla is equally guilty, so I'm not just picking on MS.
Should proper mail netiquitte be included on the mail subscription page? The
FAQ that comes periodically in the DocBook mailing list spells out proper
quoting technique (snip-quote-reply) rather nicely, and establishes policies
for attachments and cross posting.
--
Michael Westbay
Work: Beacon-IT http://www.beacon-it.co.jp/
Home: http://www.seaple.icc.ne.jp/~westbay
Commentary: http://www.japanesebaseball.com/
Re: The documentation, xml, and stylesheets
Posted by Ted Husted <hu...@apache.org>.
This is true. The styles we are using now are minimalistic, and you
probably won't need to refer to the stylesheet at all. Just monkey
what's already there ;-). The only real pain is that the XML needs to
compile properly, and if I try it by hand it usualy takes a few tries.
Tools that check the XML syntax beforehand are very helpful. I've tried
XML Writer, which was very good, but would like to try some others as
well (like XML cookbook).
Personally, I start things as plain text (in my editor) until I get near
the final draft, and then add the mark up at the end.
Martin Cooper wrote:
>
> You probably won't have to do much, if anything, with stylesheets unless you
> need to break away from the documentation style currently used by Struts.
> The stylesheets for that, obviously, are already in place, and you don't
> have to look at them if you don't want to. :-)
>
> --
> Martin Cooper
Re: The documentation, xml, and stylesheets
Posted by Martin Cooper <ma...@tumbleweed.com>.
You probably won't have to do much, if anything, with stylesheets unless you
need to break away from the documentation style currently used by Struts.
The stylesheets for that, obviously, are already in place, and you don't
have to look at them if you don't want to. :-)
--
Martin Cooper
----- Original Message -----
From: "Jonathan" <ja...@i-2000.com>
To: <st...@jakarta.apache.org>
Sent: Sunday, June 17, 2001 2:57 PM
Subject: The documentation, xml, and stylesheets
> Yea, but now I will have to learn the dtd and create complex stylesheets.
> Gentlemen. if I may be frank, this is an excercise in technical
> masturbation. If I ever want to redo it all.....than I will. Stylesheets
do
> not help, and those that have had to use them know exactly what I am
talking
> about.
>
> ----- Original Message -----
> From: "Ted Husted" <hu...@apache.org>
> To: <st...@jakarta.apache.org>
> Sent: Sunday, June 17, 2001 6:05 AM
> Subject: Re: I would like to offer myself to help with documentation
>
>
> > Jonathan wrote:
> > > It would be nice if it was just simple. Stylesheets are not. Why
dont
> we
> > > just use html
> >
> > Half the time, I think just to make my life more difficult ;-)
> >
> > The other half, I think so that we can
> >
> > * Ensure formatting consistency,
> > * Change the look without editing the content,
> > * Generate navigational constructs (though we could use more of this),
> > * and, practice what we preach.
> >
> > Most, if not all, of the Jakarta sub-project Web sites are based on XML.
> >
> > Personally, I believe there's a desperate need for more XML editing
> > tools. Everyone please keep posting any XML links you find here, and
> > I'll start a list.
> >
> >
> > -- Ted Husted, Husted dot Com, Fairport NY USA.
> > -- Custom Software ~ Technical Services.
> > -- Tel 716 737-3463.
> > -- http://www.husted.com/about/struts/
> >
>
Re: The documentation, xml, and stylesheets
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Sun, 17 Jun 2001, Jonathan wrote:
> Yea, but now I will have to learn the dtd and create complex stylesheets.
> Gentlemen. if I may be frank, this is an excercise in technical
> masturbation. If I ever want to redo it all.....than I will. Stylesheets do
> not help, and those that have had to use them know exactly what I am talking
> about.
>
Nevertheless, XML that is converted to HTML is the standard for Struts
documentation that is included with Struts. I'm not personally at all
interested in alternatives at the moment.
Craig
> ----- Original Message -----
> From: "Ted Husted" <hu...@apache.org>
> To: <st...@jakarta.apache.org>
> Sent: Sunday, June 17, 2001 6:05 AM
> Subject: Re: I would like to offer myself to help with documentation
>
>
> > Jonathan wrote:
> > > It would be nice if it was just simple. Stylesheets are not. Why dont
> we
> > > just use html
> >
> > Half the time, I think just to make my life more difficult ;-)
> >
> > The other half, I think so that we can
> >
> > * Ensure formatting consistency,
> > * Change the look without editing the content,
> > * Generate navigational constructs (though we could use more of this),
> > * and, practice what we preach.
> >
> > Most, if not all, of the Jakarta sub-project Web sites are based on XML.
> >
> > Personally, I believe there's a desperate need for more XML editing
> > tools. Everyone please keep posting any XML links you find here, and
> > I'll start a list.
> >
> >
> > -- Ted Husted, Husted dot Com, Fairport NY USA.
> > -- Custom Software ~ Technical Services.
> > -- Tel 716 737-3463.
> > -- http://www.husted.com/about/struts/
> >
>
>