Menu
▾
▴
generguide-devel — Discussion for developers of generguide
You can subscribe to this list here.
| 2003 |
Jan
|
Feb
|
Mar
|
Apr
|
May
|
Jun
(33) |
Jul
(21) |
Aug
(20) |
Sep
(80) |
Oct
(62) |
Nov
(8) |
Dec
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2004 |
Jan
|
Feb
|
Mar
|
Apr
|
May
(1) |
Jun
(4) |
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
(2) |
| 2006 |
Jan
|
Feb
|
Mar
(1) |
Apr
|
May
|
Jun
|
Jul
(3) |
Aug
(6) |
Sep
(1) |
Oct
(6) |
Nov
(7) |
Dec
(12) |
| 2007 |
Jan
(9) |
Feb
(12) |
Mar
(1) |
Apr
(4) |
May
(6) |
Jun
(11) |
Jul
(16) |
Aug
(19) |
Sep
|
Oct
|
Nov
|
Dec
|
|
From: Artur H. <ko...@pl...> - 2003-09-15 12:14:13
|
> > I'd like to look around and see what other > > alternatives we have. ENTITIES are > > starting to look more attractive to me again. > Yep. This also bothers me. But it's a trade. To me > entities are the way if you are prepared to give up > the notion that every document needs to be > independently validated and hence transformable. Sean, example code Cameron sent was not for modular documentation and file inclusion but for project customization and variables set. For this we can use one, external file defining all required entities we want to use in project. I think that for customization with variables inside documents entities are better solution than <xinclude>. As I see from Cameron's example <xicnlude> is just to complicated for this task. However for modular documentation and file inclusion <xinclude> is much better and give us flexibility we need. It seems to me very important that all documents are valid XML files, so all files can be edited in structural editors exactly the same way. I suggest to try implement environment for these to tasks as follows: 1. Customization with entities 2. Modularity with <xinclude> I would like to discuss this during our meeting. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ http://maven-plugins.sourceforge.net/ |
|
From: Artur H. <ko...@pl...> - 2003-09-15 11:58:47
|
Hi, > The bad new is that XXE doesn't recognise the xpath. :( In what sense it doesn't recognise xpath? Does it try to resolve it in some way? Should it just leave <xinclude> element as is? > The other problem is that the <xinclude> tag requires 2 lines of text for one > variable, compared to an ENTITY which only takes one word. Yes, you are right. While it is acceptable that inclusion of external file takes two lines of code, it does not well look if simple variable takes that amount of space. Readability is decreasing: The purpose of &projectname; project.... (looks fine) The purpose of <xi:include href="resources/generconfig.xml#xpointer(/generconfig/varset/var[@name='projectname']/text())"/> project.... (looks ugly) > I'd like to look around and see what other alternatives we have. ENTITIES are > starting to look more attractive to me again. Cameron, I think we should look for another editor in place of xxe not because of <xicnlude> and <xpath> support but rather because of good support for entities. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ http://maven-plugins.sourceforge.net/ |
|
From: Sean W. <se...@ya...> - 2003-09-15 11:22:01
|
--- Cameron Shorter <ca...@sh...> wrote: > I've created a demo file which uses xinclude to > reference a variable. See > attached. > The good news is xsltproc will process it. > cvs update -d . > cp x.xml generguide/guide > cd generguide/guide > xsltproc --novalid --xinclude > ../docbook-xsl/html/docbook.xsl x.xml > x.html > > The bad new is that XXE doesn't recognise the xpath. > :( > Sean, I don't suppose you can find an editor which > will handle x.xml? I use Oxygen, so I am sitting with Xerces and Xalan. But if I edit under Oxygen, there is no problem. Mainly because it is not trying to be half WYSIWYG:-) Couldn't't resist. I will try it under Morphon and see if it works, when I get a chance. > > The other problem is that the <xinclude> tag > requires 2 lines of text for one > variable, compared to an ENTITY which only takes one > word. > > I'd like to look around and see what other > alternatives we have. ENTITIES are > starting to look more attractive to me again. > Yep. This also bothers me. But it's a trade. To me entities are the way if you are prepared to give up the notion that every document needs to be independently validated and hence transformable. There is another problem. Larger IMHO. Modular documentation means that a document may xref to an ID that is not contained in the current document or any of siblings. If the ID is in the Child document, it is valid. If the ID is in the Parent it is invalid, unless validation starts from the root document. If not you need to perform an additional process to resolve all links in a separate file. Like Bob Stanton suggests at SageHill. There is no easy answer. Unless you want to create an authoring application that abstracts all aspects of XML Publishing and hence protects the author from these types of issues. Arbortext did it nicely. http://www.arbortext.com/ If you want to pay the price which IMHO is reasonable. Sean Wheller __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Sean W. <se...@ya...> - 2003-09-15 11:03:13
|
C U both then. --- Artur Hefczyc <ko...@pl...> wrote: > > Monday is better for me as I'm not contributing to > the geotools meeting much. > > Artur may prefer us to pospone until Tuesday. > Both times are good for me, I will be on-line today > - on Monday evening > and can be on-line also on Tuesday. > > Artur > -- > Artur Hefczyc > Open Source Developer > http://generguide.sourceforge.net/ > http://www.geotools.org/ > http://wttools.sourceforge.net/ > http://maven-plugins.sourceforge.net/ > > > ------------------------------------------------------- > This sf.net email is sponsored by:ThinkGeek > Welcome to geek heaven. > http://thinkgeek.com/sf > _______________________________________________ > generguide-devel mailing list > gen...@li... > https://lists.sourceforge.net/lists/listinfo/generguide-devel __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Sean W. <se...@ya...> - 2003-09-15 11:00:21
|
--- Cameron Shorter <ca...@sh...> wrote: > On Sunday 14 Sep 2003 8:09 pm, Sean Wheller wrote: > > I would like to base myself on what ever > information > > you can provide. Is the > > anything else in addition to the requirements on > SF > > and the golas on your > > Web Site? Please do send them. > > Most of it is written in the requirements in the > http://generguide.sf.net > site. > There is still a few ideas I have that has not made > it onto the site yet, but > I will try and get it on paper soon. Look forward to it. > > > My structure for an SRS is derived from IEEE Guide > to > > Software > > Requirements Specifications (Std 830-1993). It > will be > > a single Docbook XML > > file to start with. > > <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML > > V4.2//EN" > > I just looked in google for Std 830-1993. It seems > you need to pay big $$$ to > get a copy of it! :-) Yes. But as this is what I do for a living, I normally have to shed a few $$$. While I cannot legally distribute a copy of the standard. I can send you a Template (DocBook XML). This is my standard rendition of their SRS. So the outline is slightly modified and is commented at each section. We will be free to use the template without legal implication as it is a work of my own, simply based on the recommendations. > While a think it is very important to use standards > where possible, in an open > source project I think it is more important to only > use free and open > standards. > At work we are using Mil-Std-498. It is available > for free at: > http://www.pogner.demon.co.uk/mil_498/ I have no problem using MIL. There is no huge difference between them. Just that in general MIL is a little dated and does not fall nicely into place with ISO std's such as ISO 18019. > > Secondly, I suggest we use Simple Docbook XML > instead of Docbook XML. It has > a lower learning curve for potential editors. > Would it be possible for you to use Simple Docbook > instead? I guess I can, but does it matter. Anyone who can modify the SRS should be at a level where the have a broader perspective of XML. If they are editing the SRS I assume that they have at least an understanding of XML, XSL, XPath, XInclude, XPointer etc. But if you feel that sdocbook must be used, I will use it. Though now I will have to create a new template based on the sdocbook type. Sean Wheller __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-15 10:30:55
|
I've created a demo file which uses xinclude to reference a variable. See attached. The good news is xsltproc will process it. cvs update -d . cp x.xml generguide/guide cd generguide/guide xsltproc --novalid --xinclude ../docbook-xsl/html/docbook.xsl x.xml > x.html The bad new is that XXE doesn't recognise the xpath. :( Sean, I don't suppose you can find an editor which will handle x.xml? The other problem is that the <xinclude> tag requires 2 lines of text for one variable, compared to an ENTITY which only takes one word. I'd like to look around and see what other alternatives we have. ENTITIES are starting to look more attractive to me again. -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Artur H. <ko...@pl...> - 2003-09-15 10:17:53
|
> Monday is better for me as I'm not contributing to the geotools meeting much. > Artur may prefer us to pospone until Tuesday. Both times are good for me, I will be on-line today - on Monday evening and can be on-line also on Tuesday. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ http://maven-plugins.sourceforge.net/ |
|
From: Cameron S. <ca...@sh...> - 2003-09-15 09:35:01
|
Monday is better for me as I'm not contributing to the geotools meeting much. Artur may prefer us to pospone until Tuesday. On Monday 15 Sep 2003 5:03 pm, Sean Wheller wrote: > --- Cameron Shorter <ca...@sh...> wrote: > > I confused myself. > > Monday here in Sydney is Sunday in Johanasburg. :) > > Let's try again for Monday in Johanasburg/Tuesday in > > Sydney. > > > > Note, this is the same time as the Geotools IRC > > meeting Artur and I particpate > > in. (We will both be online, but may be > > distracted). > > The following day may be better. > > Yep, I thought it was for tonight. JHB. > > Do you prefer Monday or Tuesday? It was not clear > which day the geotools meeting is on. > > Sean > > __________________________________ > Do you Yahoo!? > Yahoo! SiteBuilder - Free, easy-to-use web site design software > http://sitebuilder.yahoo.com -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-15 08:27:46
|
On Sunday 14 Sep 2003 8:10 pm, Sean Wheller wrote: > The permeations of this theory can spin our heads for > a year. So I ask the > question. Is CVS the tool for the job? Perhaps we need > CVS and an XML > Database, maybe just the database with an application > layer above it. CMS > and KMS? What tools do we recommended and what tools > do we use. CVS is the de-facto standard of open source projects. It is likely to be replace by subversion in a year or 2, however subversion is just a rewrite of CVS and will have CVS imports. Hence it would take a lot to convince me that we should not use CVS. With regards to releases and whether we access sections on a per file basis or per release basis: Ie, should we reference: /project/<release>/file.xml or /project/file_<version>.xml Again, I refer to convensions in releasing standards and software libraries. In both cases, projects convensionally provide releases. It is possible for the version of a file in one release to be the same in the next release. While I acknowledge that documentation could logically be released on a per file basis, it would make referencing the documentation more complicated. In this case, I think we should sacrifice flexibility in order to Keep It Simple. -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-15 08:27:45
|
On Sunday 14 Sep 2003 8:09 pm, Sean Wheller wrote: > I would like to base myself on what ever information > you can provide. Is the > anything else in addition to the requirements on SF > and the golas on your > Web Site? Please do send them. Most of it is written in the requirements in the http://generguide.sf.net site. There is still a few ideas I have that has not made it onto the site yet, but I will try and get it on paper soon. > My structure for an SRS is derived from IEEE Guide to > Software > Requirements Specifications (Std 830-1993). It will be > a single Docbook XML > file to start with. > <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML > V4.2//EN" I just looked in google for Std 830-1993. It seems you need to pay big $$$ to get a copy of it! While a think it is very important to use standards where possible, in an open source project I think it is more important to only use free and open standards. At work we are using Mil-Std-498. It is available for free at: http://www.pogner.demon.co.uk/mil_498/ Of particular use to us is the SRS DID (search for it on the left hand frame) which provides a template for writing a SRS. Mil-Std 498 has been replace by ISO 12207, however 12207 costs money to obtain and hence I don't think we should use it. I'm open to other suggestions. Secondly, I suggest we use Simple Docbook XML instead of Docbook XML. It has a lower learning curve for potential editors. Would it be possible for you to use Simple Docbook instead? -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Sean W. <se...@ya...> - 2003-09-15 07:03:37
|
--- Cameron Shorter <ca...@sh...> wrote: > I confused myself. > Monday here in Sydney is Sunday in Johanasburg. :) > Let's try again for Monday in Johanasburg/Tuesday in > Sydney. > > Note, this is the same time as the Geotools IRC > meeting Artur and I particpate > in. (We will both be online, but may be > distracted). > The following day may be better. Yep, I thought it was for tonight. JHB. Do you prefer Monday or Tuesday? It was not clear which day the geotools meeting is on. Sean __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-14 21:51:51
|
I confused myself. Monday here in Sydney is Sunday in Johanasburg. :) Let's try again for Monday in Johanasburg/Tuesday in Sydney. Note, this is the same time as the Geotools IRC meeting Artur and I particpate in. (We will both be online, but may be distracted). The following day may be better. On Sunday 14 Sep 2003 5:51 am, Cameron Shorter wrote: > Server: eu.freenode.net > Channel: #generguide > I'm getting breakfast for the kids, but will check the computer every 10 to > 15 minutes to see if you turn up. > Otherwise, let's try for tomorrow (Monday at 9:45pm your time, 5:45am > Syndey time). -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Sean W. <se...@ya...> - 2003-09-14 10:10:37
|
----- Original Message -----
From: "Cameron Shorter" <ca...@sh...>
Sent: Sunday, September 14, 2003 1:09 AM
> On Saturday 13 Sep 2003 9:53 pm, Sean Wheller wrote:
> > If CVS is managing the files and their versions.
Why
> > add to the path with a
> > version number? If a version is required, could it
not
> > be included in the
> > file name. This way regardless of the file
location,
> > the version number will
> > always be known.
>
> I envisage that there will be multiple
GenerRepositories. Each repository
> will be independantly administered from each other,
putting out their own
> releases of guides relevant to their area of
expertise. Each repository
will
> issue releases which reflect updates. Both new and
old releases need to
be
> accessable via the web by other projects.
>
> So, if I am creating a Developer's Guide for the
Linux Documentation
Project,
> I may reference the Sun Java Coding Standards
(maintained by Sun).
>
> There are 2 types of guides I may want:
> 1. A guide that doesn't change over time. I'm
developing a product which
is
> not going to upgrade it's toolset, so I want my
Developer's Guide
> configuration to always reference Java 1.4 docs. So
I reference release
4.0
> of the Sun's GenerRepository.
>
> 2. A guide that always refers to the latest
development practices. So I
> reference the head release of Sun's GenerRepository.
>
> Does this make sense?
Ok, I think I get the picture. At the end you see
people referencing only
the head, hence you want version control in both the
path and file level.
When a new version is released it is copied to a new
repository. The
previous version then remains in its final state and
is not touched. That
way the integrity of my reference to a file in the
head of the previous
version will be preserved. The head will always remain
the head, from a
given date when the new version was started.
While this is a solution, I think we will have
additional overhead and
duplication of content between versions. I am not sure
that this is needed.
Horizontal Thinking.
A file is created called blue.xml. The file is
modified and a new version
exists. We now have two files in CVS, blue_v1.xml and
blue_v2.xml
A file is created called red.xml. The file is modified
and a new version
exists. The file is again modified and a new version
exists. We now have
three new files in CVS, red_v1.xml and red_v2.xml and
red_v3.xml
Horizontally all files increment a version in this way
until the release. If
no more changes are made we have a total of 5 files in
the CVS for our
release.
Vertical Thinking.
release 1 = blue_v2.xml and red_v3.xml
Now lets move ahead a few releases.
release 2 = blue_v2.xml and red_v4.xml
release 3 = blue_v2.xml and red_v5.xml and
yellow_v1.xml
release 4 = blue_v2.xml and red_v5.xml and
yellow_v2.xml
release 5 = blue_v2.xml and red_v5.xml and
yellow_v3.xml
By the pattern you can see that if we were to create a
new repository folder
for each version, then the file blue_v2.xml would
exist in duplicate 6 times
and red_v5.xml 3 times. Subsequent releases would
further increase
duplication is the files are not incremented a version
because of some
modification.
In a book I need version control not only of the
included XML Instances, but
also of the book itself. However, I do not need to
always have a new or
duplicate copy of the files. In the example below " "
is used to represent
use of a file from the previous release.
Book 1 = release 2(blue_v2.xml, red_v4.xml)
Book 2 = release 3(" ", red_v5.xml,
yellow_v1.xml)
Book 3 = release 4(" ", " ",
yellow_v2.xml)
Book 4 = release 5(" ", " ",
yellow_v3.xml)
Book 5 = release 6(" ", red_v6.xml,
" ")
Book 6 = release 7(" ", " ",
yellow_v4.xml)
All files exist only once in their final release
state. A book may use any
file from any release.
Book 7 = release 8(" ", red_v4.xml,
yellow_v5.xml)
red_v4.xml was from release 2, but if the author finds
the content in
red_v4.xml to be better suited, it may be reused in a
future book, this case
Book 7.
Note that each book remains in version control as do
all the files.
Flexibility is great, content reuse optimised.
I don't know enough about CVS at lower levels to say
if this is possible,
mainly because I always refer to the head. But it is
apparent that the head
itself is made of files with varying ages and as with
Book 7 it may or may
not present a problem. To the current author of Book 7
it is not a problem.
To a future author it may be a problem as red_v6.xml
will not be known. The
collaborative environment presents many challenges.
Certainly I would like to have the ability to discover
all content.
Investigate its lineage and select a version that best
suits my
requirements. Used it unaltered or modify it to a new
version. If I modify
to create a new version of red_v5.xml, I cannot name
the file red_v6.xml it
would have to branch at red_v5.1.xml. My version is
then free to discovered
and used by other authors.
The permeations of this theory can spin our heads for
a year. So I ask the
question. Is CVS the tool for the job? Perhaps we need
CVS and an XML
Database, maybe just the database with an application
layer above it. CMS
and KMS? What tools do we recommended and what tools
do we use.
Sean Wheller
__________________________________
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com
|
|
From: Sean W. <se...@ya...> - 2003-09-14 10:09:56
|
----- Original Message ----- From: "Cameron Shorter" <ca...@sh...> Sent: Saturday, September 13, 2003 11:52 PM > On Saturday 13 Sep 2003 9:54 pm, Sean Wheller wrote: > > > The problem is change. We humans do not like it, but > > we must if we are to > > evolve. I think that for the good of development, that > > I should review the > > requirements and do more research about generguide. > > That way you can get on > > with coding and our paths will meet down the track. > > All I need to know is > > that dev is not going to hate me or reject all the > > recomendations when I am > > finished. > > Sounds good to me, and I will welcome your feedback. > We are reaching the standard question in all projects: > "Do we release early, even though our implementation is flawed, or do we start > again, this time doing a better job?" > The answer changes each time you ask the question. > > I'd like to release soon, even though the product has it's flaws. However we > should only call it a "prototype" or "technology demonstrator" or something. > The aim of the release is to attract developers who might be tempted to start > their own project in competition with ours. A hard question. Release early is better but we will have to set some standards. You have already released one version. So the barrier to entry from others is limited to some extent. I think, as I am new and I am the cat amongst the pigeons, that you must go ahead with plans. I will slot in. Anyway, I need your input on the SRS and the more people we have the better. > > > > > Ditto. I think I will start at this point. I will > > output a SRS for us to > > colaborate on. > > For the record, SRS = Software Requirements Specification. > Great. > I'd be interested to know whether you would like to use my Requirements as a > starting point, or whether you want to start again from scratch. I'd prefer > it if you extended existing requirements, but am happy if you start again if > you think it will be easier. > I'd like to know whether you consider the format of the current requirements > could be improved. If you want to start using a new format, could you please > ensure that all "shalls" have a unique id so that we can cross reference it > with the design. > Unfortunately, I have been unable to find a good open source requirements > editor. You can see further thoughts on it at: > http://cameron.shorter.net/goals.html#requirementstracing > I would like to base myself on what ever information you can provide. Is the anything else in addition to the requirements on SF and the golas on your Web Site? Please do send them. My structure for an SRS is derived from IEEE Guide to Software Requirements Specifications (Std 830-1993). It will be a single Docbook XML file to start with. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> I am using a CATALOG to map to my local copy of the DTD. I don't know how you guys work, but with CATALOG the document will validate on any of our systems. > > Yep. At present it is hard to know how to use > > generguide. > > I guess the Users' Guide must have been written by a programmer instead of a > tech writer. :) > Have you executed the generpublish.sh script yet? > Using generguide involves running generpublish.sh from a unix command line > (cygwin on windows). This is beyond the expertise we should expect from a > tech writer. > Hence, I think I should focus on writing a CGI wrapper on top of > generpublish.sh so that it can be driver from a web page. I don't think it > will be too difficult to write and will be a great technology demonstrator. Yes. At present I can only put time to GenerGuide at weekends. This is from home and at present I am on a Windows machine. I am waiting for my other computers to arrive from AU. I just spent seven months down there on contract to Medibank Private (Melbourne). My Linux box is enroute. At the office I have Linux and Windows, but little time to play with Generguide. I have looked at generguide and am busy putting the pieces together. Using Cygwin is a %$#@. No Worries, I will get it sorted. Soon we will be cooking with gas again. > > > Do you know about > > e-novative DocBook Environment (eDE)? > No. > > > http://www.e-novative.de > > > > Take a look an tell me what you think. > > The english version of the site is down, but I was able to find the following > review: > > The e-novative DocBook Environment (eDE) is a free, ready-to-go integrated > environment for Windows enabling you to various output formats from DocBook > XML sources. Currently a single HTML page, multiple HTML pages and PDF output > are supported. eDE installs in a snap and lets you create output files with > one command line command. Supports articles and books, includes > well-documented customization. > > -- > Sounds like eDE provides similar functionality to xsltproc? > Maybe it is easier to install? It is easy to install, but it is only for Windows. I just thought that some ideas could be taken or learnt from them. In terms of processing tools. Sean Wheller __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-13 23:09:52
|
On Saturday 13 Sep 2003 9:53 pm, Sean Wheller wrote: > If CVS is managing the files and their versions. Why > add to the path with a > version number? If a version is required, could it not > be included in the > file name. This way regardless of the file location, > the version number will > always be known. I envisage that there will be multiple GenerRepositories. Each repository will be independantly administered from each other, putting out their own releases of guides relevant to their area of expertise. Each repository will issue releases which reflect updates. Both new and old releases need to be accessable via the web by other projects. So, if I am creating a Developer's Guide for the Linux Documentation Project, I may reference the Sun Java Coding Standards (maintained by Sun). There are 2 types of guides I may want: 1. A guide that doesn't change over time. I'm developing a product which is not going to upgrade it's toolset, so I want my Developer's Guide configuration to always reference Java 1.4 docs. So I reference release 4.0 of the Sun's GenerRepository. 2. A guide that always refers to the latest development practices. So I reference the head release of Sun's GenerRepository. Does this make sense? -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-13 21:53:19
|
On Saturday 13 Sep 2003 9:54 pm, Sean Wheller wrote: > The problem is change. We humans do not like it, but > we must if we are to > evolve. I think that for the good of development, that > I should review the > requirements and do more research about generguide. > That way you can get on > with coding and our paths will meet down the track. > All I need to know is > that dev is not going to hate me or reject all the > recomendations when I am > finished. Sounds good to me, and I will welcome your feedback. We are reaching the standard question in all projects: "Do we release early, even though our implementation is flawed, or do we start again, this time doing a better job?" The answer changes each time you ask the question. I'd like to release soon, even though the product has it's flaws. However we should only call it a "prototype" or "technology demonstrator" or something. The aim of the release is to attract developers who might be tempted to start their own project in competition with ours. > > Ditto. I think I will start at this point. I will > output a SRS for us to > colaborate on. For the record, SRS = Software Requirements Specification. Great. I'd be interested to know whether you would like to use my Requirements as a starting point, or whether you want to start again from scratch. I'd prefer it if you extended existing requirements, but am happy if you start again if you think it will be easier. I'd like to know whether you consider the format of the current requirements could be improved. If you want to start using a new format, could you please ensure that all "shalls" have a unique id so that we can cross reference it with the design. Unfortunately, I have been unable to find a good open source requirements editor. You can see further thoughts on it at: http://cameron.shorter.net/goals.html#requirementstracing > Yep. At present it is hard to know how to use > generguide. I guess the Users' Guide must have been written by a programmer instead of a tech writer. :) Have you executed the generpublish.sh script yet? Using generguide involves running generpublish.sh from a unix command line (cygwin on windows). This is beyond the expertise we should expect from a tech writer. Hence, I think I should focus on writing a CGI wrapper on top of generpublish.sh so that it can be driver from a web page. I don't think it will be too difficult to write and will be a great technology demonstrator. > Do you know about > e-novative DocBook Environment (eDE)? No. > http://www.e-novative.de > > Take a look an tell me what you think. The english version of the site is down, but I was able to find the following review: The e-novative DocBook Environment (eDE) is a free, ready-to-go integrated environment for Windows enabling you to various output formats from DocBook XML sources. Currently a single HTML page, multiple HTML pages and PDF output are supported. eDE installs in a snap and lets you create output files with one command line command. Supports articles and books, includes well-documented customization. -- Sounds like eDE provides similar functionality to xsltproc? Maybe it is easier to install? -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Sean W. <se...@ya...> - 2003-09-13 11:55:08
|
----- Original Message ----- From: "Cameron Shorter" <ca...@sh...> Sent: Saturday, September 13, 2003 6:16 AM Subject: Stable requirements > On Friday 12 Sep 2003 3:55 pm, Sean Wheller wrote: > > I think that requirements need to be defined that will > > address portability. > Yes. > > On Friday 12 Sep 2003 3:55 pm, Sean Wheller wrote: > > The track sounds right. But I think that the > > requirements etc need to be stable before investing so > > much time is developing tools. Once stable, then the > > wish list can be attacked. > > Yes and no. > The requirements were reasonably stable until you came along with a pile of > great ideas. :) Yes, I do feel like a cat set amongst the pigeons. I anticipate that any new developer will have the same effect on GenerGuide. This is precisely why the issue of stable requirements is of some concern to me. Perhaps it's just me. But I like to develop on stable and unified vision first. Then, along the way collect ideas and discuss revisions to requirements as and when the development cycle permits. This way the target and release is not interupted. Like others I see little or no point of developing when I know that the vision is broken. I anticipate that others will feel the same. The problem is change. We humans do not like it, but we must if we are to evolve. I think that for the good of development, that I should review the requirements and do more research about generguide. That way you can get on with coding and our paths will meet down the track. All I need to know is that dev is not going to hate me or reject all the recomendations when I am finished. > > Part of refining requirements involves developing a prototype which will flush > out a number of the issues you don't understand of have not thought of. Yes, but take it in small steps, standards based. Make the foundation strong and work. Then enhance in small steps. > > However, I agree we need to capture the ideas from this discussion in the > requirements. Ditto. I think I will start at this point. I will output a SRS for us to colaborate on. > We also need to update the design as we develop it, as it also explains to > ourselves and future developers why we have chosen the design we are using. Yep. At present it is hard to know how to use generguide. Do you know about e-novative DocBook Environment (eDE)? http://www.e-novative.de Take a look an tell me what you think. Sean __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Sean W. <se...@ya...> - 2003-09-13 11:55:00
|
----- Original Message ----- From: "Cameron Shorter" <ca...@sh...> Sent: Saturday, September 13, 2003 6:16 AM > On Friday 12 Sep 2003 3:55 pm, Sean Wheller wrote: > > > 2. Commented entities are difficult to work with, > > > but it is closely associated > > It seems Sean misunderstands our attitude to commented entities. > The reason we are using commented entities is a hack to get around the > difficienties of XXE and something we plan to remove as soon as we stop > talking and get back to coding. > Currently we use: <!--&project_name;--> in our souce text. Pre-processing > from the generpublishing script converts this to &project_name; . > "project_name" is defined as an entity in guide/resouces/entities.ent Yes I have seen this in the source and naturally I was a bit confused at first about how to process. I had to make the connection between the script and what it did to the commented entities. If I was not able to read or understand the script I would have dropped generguide then and there. Considering that most authors will not have the patience for trial and discovery. I thought that the solution was one barrier to entry that was not required. I managed my entities in a very simple way. I have a jscript and a perl script which I found on bayes.co.uk. Its called dir2xml. I run the script to get a recurvise listing of a directory in XML. Then I wrote an XSL to convert the XML to a file called global.ent. It is inlcuded in the prolog as an external entity. I see you use this standard technique in generguide already. global.ent contains the entity list in standard syntax format <!ENTITY entity_name SYSTEM "/path/to/filename.xml"> Example: <!ENTITY file SYSTEM "/path/to/file.xml"> Every file in the directory has an entry. So I can insert an entity reference when ever I wish. Naturally the content of the XML Instance must be Well-formed and Valid. It must also be acceptable within the context of the element to which it is inserted. <para>The file <filename>file.xsd</filename> is used to validate XML Instances passed to the Business Object</para> Would be: <para>The file &file; is used to validate XML Instances passed to the Business Object</para> I have not further need for any pre-processing. All I must remember is that when I add a new file to the document, it must be added to global.ent. This is easy as I just run the script > xsl > global.ent If I don't then the validator will complain. The problem I have with the current <!-- --> method is that it is non-standard solution introduced because of XXE. Yet when I use the method described above, I can still use XXE. The previous version had the nasty side effect of importing the value contained in file.xml into the master document. The current version no longer does this, but you cannot edit the external XML Instance directly. This is fine as I can always open file.xml seperately. Hence I was pressing to get the <!-- --> method removed as soom possible. > > What we plan to do is replace the above with xlinks which reference the > generconfig.xml file. (I haven't worked out how to do this yet and am not > sure if XXE supports it, but I plan to look at it soon). As I see it generconfig.xml is just a filter that enables you to decide what is in and what is inlcuded and what is excluded from output. While this is certainly a method that works. I wonder why it is required? In my system I create an entry for all XML Instances within the folder. The root document includes several files by way of external entity reference and those files can include further files. If I don't want to have a file, then I and exclude as required using <!-- --> or delete the entity reference. Ok, I must conform to some rules, like each IDREF must be unique in the root document and DOCTYPE cannot be in any of the documents referenced by the root document. But this is not a major problem as I <!-- --> out any DOCTYPE below the root. The problem is that each XML Instances is then not a valid document in itself. XInlcude provides a solution to this, but as we know it needs a helper until such time that more tools support it. Still, without the aid of XInlcude. I have a highly granualar and flexible pool of information resources. The granularity of my system can be as fine or as general as I want. XML Instances can be the source of a value or could be comprised of the values contained in two or more external XML Instances (It does not make much sense to do this with just one value). > > Sean, you are rightly concerned that we are not using standards, and I agree > that we need to move back to using standards. (I think this is the only > place where we have deviated from standards.) Cool > > -- > > With regards to normal Entities from legacy documentation. They can still be > used within the current generguide framework. We are not planning to remove > this functionality. Good to hear. > > --- > On Saturday 13 Sep 2003 3:28 am, Sean Wheller wrote: > > Do we set a standard. In some respects yes. In others > > no. When it comes to tools and their technological > > functionality. I think NO. When it comes to a > > Framework that works with most Publishing Models, I > > think YES. > > I agree. > I believe the job of generguide is: > 1. Define the interface. Ie Docbook XML using modular docs. > 2. Ensure at least one free editor supports this interface and your average > tech writer is happy using it. Ie, WYSIWYM, edits docbook xml, supports > modular documents. > 3. Provide publishing tools. Cool. __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Sean W. <se...@ya...> - 2003-09-13 11:54:20
|
----- Original Message ----- From: "Cameron Shorter" <ca...@sh...> Sent: Saturday, September 13, 2003 6:16 AM > Sean and Artur, are you receiving emails through the generguide email list? > If so, we should be able to revert back to using just that list now. (I put > in a trouble report with sourceforge and it seems to be resolved now). Yes > > On Friday 12 Sep 2003 12:41 am, Artur Hefczyc wrote: > > > 5. Introduce concept of GenerRepository. Allow generconfig to reference > > > sections from other GenerRepositories. Need to address versions, copying > > > images, sections from different repositories having the same id. > > > > Well, I was thinking about building document from sections with following > > <xinclude> use: > > <xi:include href="http://generguide.sf.net/guide/versionnumbers.xml"/> > > I mean to reference parts from source, web location and not from local > > file system, to not force user to keep all files localy. > > They can be kept localy to speed processing up, but main reference should > > be to source location. > > Yes, I agree, this will be particularly important when creating multiple > repositories, however we I think we can still allow relative links. Both mechanism work. The user should have the choice. > > I think we also need to introduce a GenerRepository version number into the > directory structure, so we will get the following types of links: > > <xi:include href="http://gnu.org/guide/1_1_0/gpl.xml"/> > <xi:include href="http://gnu.org/guide/head/gpl.xml"/> > <xi:include href="http://gnu.org/guide/stable/gpl.xml"/> > <xi:include href="license.xml"/> > If CVS is managing the files and their versions. Why add to the path with a version number? If a version is required, could it not be included in the file name. This way regardless of the file location, the version number will always be known. Sean Wheller __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-13 04:17:12
|
On Friday 12 Sep 2003 3:55 pm, Sean Wheller wrote: > I think that requirements need to be defined that will > address portability. Yes. On Friday 12 Sep 2003 3:55 pm, Sean Wheller wrote: > The track sounds right. But I think that the > requirements etc need to be stable before investing so > much time is developing tools. Once stable, then the > wish list can be attacked. Yes and no. The requirements were reasonably stable until you came along with a pile of great ideas. :) Part of refining requirements involves developing a prototype which will flush out a number of the issues you don't understand of have not thought of. However, I agree we need to capture the ideas from this discussion in the requirements. We also need to update the design as we develop it, as it also explains to ourselves and future developers why we have chosen the design we are using. -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-13 04:17:04
|
On Friday 12 Sep 2003 3:55 pm, Sean Wheller wrote: > > 2. Commented entities are difficult to work with, > > but it is closely associated It seems Sean misunderstands our attitude to commented entities. The reason we are using commented entities is a hack to get around the difficienties of XXE and something we plan to remove as soon as we stop talking and get back to coding. Currently we use: <!--&project_name;--> in our souce text. Pre-processing from the generpublishing script converts this to &project_name; . "project_name" is defined as an entity in guide/resouces/entities.ent What we plan to do is replace the above with xlinks which reference the generconfig.xml file. (I haven't worked out how to do this yet and am not sure if XXE supports it, but I plan to look at it soon). Sean, you are rightly concerned that we are not using standards, and I agree that we need to move back to using standards. (I think this is the only place where we have deviated from standards.) -- With regards to normal Entities from legacy documentation. They can still be used within the current generguide framework. We are not planning to remove this functionality. --- On Saturday 13 Sep 2003 3:28 am, Sean Wheller wrote: > Do we set a standard. In some respects yes. In others > no. When it comes to tools and their technological > functionality. I think NO. When it comes to a > Framework that works with most Publishing Models, I > think YES. I agree. I believe the job of generguide is: 1. Define the interface. Ie Docbook XML using modular docs. 2. Ensure at least one free editor supports this interface and your average tech writer is happy using it. Ie, WYSIWYM, edits docbook xml, supports modular documents. 3. Provide publishing tools. -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-13 04:16:50
|
This thread is getting very complicated, so I plan to take Sean's advice and break the email into seperate threads. Sean and Artur, you have been very talkative while I was sleeping! It is going to take a bit for me to catch up. Sean and Artur, are you receiving emails through the generguide email list? If so, we should be able to revert back to using just that list now. (I put in a trouble report with sourceforge and it seems to be resolved now). On Friday 12 Sep 2003 12:41 am, Artur Hefczyc wrote: > > 5. Introduce concept of GenerRepository. Allow generconfig to reference > > sections from other GenerRepositories. Need to address versions, copying > > images, sections from different repositories having the same id. > > Well, I was thinking about building document from sections with following > <xinclude> use: > <xi:include href="http://generguide.sf.net/guide/versionnumbers.xml"/> > I mean to reference parts from source, web location and not from local > file system, to not force user to keep all files localy. > They can be kept localy to speed processing up, but main reference should > be to source location. Yes, I agree, this will be particularly important when creating multiple repositories, however we I think we can still allow relative links. I think we also need to introduce a GenerRepository version number into the directory structure, so we will get the following types of links: <xi:include href="http://gnu.org/guide/1_1_0/gpl.xml"/> <xi:include href="http://gnu.org/guide/head/gpl.xml"/> <xi:include href="http://gnu.org/guide/stable/gpl.xml"/> <xi:include href="license.xml"/> -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Cameron S. <ca...@sh...> - 2003-09-12 20:20:32
|
Hi, Artur suggested we have an IRC meeting and I agree it would be a good idea in order to thrash out some of our ideas. Sean, are you familiar with IRC (chat)? When would be a good time for everyone? Best for me is 05:45-07:15 or 19:45-21:30 in Sydney. See the following link for comparative times in your area. Sean, I assume you live in the same timezone as Johannesburg? http://www.timeanddate.com/worldclock/meetingtime.html?p1=240&p2=262&p3=111 (I accidently sent this email to another project's email list that Autur and I are subscribed to). Artur can meet us both these times above, or any other time this weekend. I may be able to make it in the afternoon as well, but time will be shorter, and I will probably be distracted by my kids. -- Cameron Shorter http://cameron.shorter.net Open Source Developer http://generguide.sourceforge.net http://mapbuilder.sourceforge.net http://geotools.org Senior Software Engineer http://www.adi-limited.com |
|
From: Artur H. <ko...@pl...> - 2003-09-12 18:47:26
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Sean, After discussion in last a few e-mails I can say, I am happy to see we have very similar approach and opinions. I must say I totally agree with almost all sentences you said in your last e-mail. So I think it is good time to start talk about details. The only concern I still have is <xinclude> ;-) Yes, I know sometimes I don't give up that easy. Anyway, with regards to <xinclude> one of us is missing something. I want to use <xinclude> because it seems to me we have sufficient support for it NOW. You don't want use <xinclude> because in your opinion there is no enough support for handling it NOW. Look here: http://dev.w3.org/cvsweb/~checkout~/2002/issues/xsl/xinclude.xsl We don't want/need to base on <xinclude> support in any of existing XML processors like xerces, saxon, xmlproc, xalan and any other. We can/want to use above XSL template with ANY xsl processor. We (me and Cameron) tested it for different tasks. I can say it works for my task very well - enough well for our (generguide) existing needs. I mean joining document parts in one XML file. I tested it with all the most popular XSL processors: xalan, saxon, and xslproc (I know the last one have built-in support but I switched it off). So using this seems the most portable - works in many different environments. Please have a look on it and try to evaluate if in your opinion it is enough for our existing needs. > I agree with you. However, there are many free XML > Editors on the market > http://www.morphon.com/index.shtml > http://www.conglomerate.org > I can give a long list. This is very good. I didn't now about them. Maybe we shouldn't worry than about xxe limitations... Cameron can say more in this matter, because he is more competent in that area. Cameron: During the this weekend I can meet on IRC at any time convenient to you. I am home alone ;) Other days I prefer your morning time, because your evening I am at work and I can't make hard plans for IRC meeting. Artur - -- Artur Hefczyc "Don't change people, just live with them." Open Source Developer: http://www.geotools.org/ http://generguide.sourceforge.net/ http://wttools.sourceforge.net/ http://maven-plugins.sourceforge.net/ -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.2 (GNU/Linux) iD8DBQE/YhSa0/6x1bjSKPkRAq2aAJ9RU/IDZ5M6T3/zIdWM1WeVFekG+wCeKmk5 N6axPr4KUuBbFofi2P20BxE= =g7q1 -----END PGP SIGNATURE----- |
|
From: Sean W. <se...@ya...> - 2003-09-12 17:29:30
|
--- Artur Hefczyc <ko...@pl...> wrote: > Hi, > > Sean, it seems to me that there is some > misunderstanding > because you don't know full story of some of our > solutions > or just we are talking about different issues. > Please, let me explain some general matters and than > we can > start discuss details again. No offense taken and none intended. I think we are both talking about the same things. It's just that many topics in one message makes life confusing for all. May I suggest we tackle issues on a one message thread per subject basis? > 1. Documentation processing: > I hope we target java and non-java projects, so > we should have > at least ready to use java tools and non-java > tools. I take part > in both kind of projects and from my experience > I know that > these are two separate worlds: > Java developers prefer to use java-only tools > and environment, however > non-java developers hate to use any java > applications. They want > to have nothing to do with CLASSPATH, installing > JDK and > all related matters. > So I can see at least 2 concurrent lines of > documentation processing tools: > - Java > - non-java I agree totally. I use both Linux and Windows. I only refer to Java as it is the only way that I can see 100% portability in a single app. The alternative to which there is no simple solution, is to have scripts for Linux and batch files for windows. Or jscript for Windows and Perl for Linux. etc. etc. I am glad that you mention the different attitudes of users, I will get back to this later. > I am thinking only about XML processing tools, > not editors. When I speak > about XML processing I mean, transformation all > source XML files into > chosen target format (one HTML file, multiple > HTML files, PDF, and so on...) Yes. The tool chain that creates a Publishing Model. http://www.nwalsh.com/docbook/procdiagram/index.html I am saying that the Publishing Model for GenerGuide should be as generic possible. Allowing any implementation of the tool chain to be capable of producing an output from GenerGuide Sources. > > These tasks are not too complicated indeed so > implementation and > maintenance of two separate lines should not be > too difficult. > > # So problem is: XML processing tools... I like to see the processing tools as having limitations. These prohibit the implementation of a Publishing Model. In my opinion we have to do with what is available and works. Unless we are prepared to actually contribute to the Xerces project and complete the implementation of XPointer etc. True full support will come alone in dues course. But do you want to fight with it until full support is provided? I would like to see it work with current technology. Keep watching the emerging stuff and port generguide when it becomes stable. > > 2. Editors: > Personally I count myself as a man who has big > XML knowledge and > I use emacs in my whole development work, both > programming and > XML documentation. Probably you are much better > than me in XML > matter. > However I hope we target also developers with > much fewer (if any) > XML knowledge. They need to use WYSIWYG or > WYSIWYM > editors, at least at starting point. So our > environment should be > prepared to use it with both kind of editors. It > even seems to me > that visual editors are even more important > because users like we > have enough knowledge to solve most problems > with XML issues, on > the contrary to beginners who just give it up. > > So we should also be aware of limitation visual > editors have. > > Xxe is the only free editor I know but as you > said it is broken and does not > allow to work well with entities for example. > > # So problem is: XML editing applications > proposition (free is essential)... I agree with you. However, there are many free XML Editors on the market http://www.morphon.com/index.shtml http://www.conglomerate.org I can give a long list. The point is that GenerGuide, as with your Java scenario, must be able to work with any and all XML editors, even the commercial ones. We can certainly point the way to free or open source tools and they certainly will reduce the barrier to entry for people that want a solution with cost. Is this the point of GenerGuide? > > 3. We want to provide framework for modular > documentation. So you > can build guide for your project from existing > blocks and add some > more bocks, specific for your project. Yes. A Generic Guide "GenerGuide", that provides a framework for authors to create documents. The GenerGuide is like a cookie cutter. It enables you to get started from a base template. Now for the modular documentation part. I ask a rhetorical question, why do we need modular documentation? Is it because we want a higher level of reuse or is it because we want greater flexibility to include and exclude ingredients from our cookie. The cutter will stay the same shape. But the cookies will taste different. I think it is both. There are more reasons, but lets just stick with that. So, in my mind I see GenerGuide as a cookie cutter. It does not change shape. I must add ingredients to make the cookies taste good or have a brown color instead of straw. Chocolate vs. Vanilla. > > As you said entities were mostly used for > parting documents. However it > seems to me they were used for this task in the > past because of lack of > better option. They have, however, a few > important limitations and it is worth > to look for better approach. First of all > system entities can not have DOCTYPE > declaration so therefore they are not valid XML > documents and working with > single entity file is more difficult - no > validation, no context prompt. > > <xinclude> was invented just for modular XML > documents. It has poor > support yet but we can expect that it will be > better in short future. I think it > is promising solution. And we have working tools > for our simple needs for now. > > Maybe you have just another idea how to manage > modular documents... > > # So the problem is: XML modular documents... Yes, I do agree with you. But we are not yet in the future. All we can do is prepare for it. In the interim we should be able to have a working version with todays technology. There is no point fighting it unless we are prepared to develop the tools in the chain ourselves. This is not an option. I think we need to aggregate the functionality of all the tools an focus on what is possible with the common. Yet stay flexible to move rapidly into new territory as it becomes available. hence the current release will be stable and the dev release will be new territory - hold onto your hat!! > > 4. We want to have reusable documents from one > project to another. I mean > we have a couple of XML files which can be used > to build instruction for > developers. But some elements in these documents > should be changed regarding > to project: project name, site address, manager > name and so on. Yes. I agree. Variables can be provided for. You can do this in the ENTITY or make an XSL that provides global parameters or fetch the variables from XML files during the XSL. The method of implementation will work which ever way. All I would like to see is that it is standard. Currently generguide needs special handling in order to make the input acceptable to the processor. Without it, the processor would throw an exception. > > Than we need some customization for documents. > Our solution was entities > and we can define values of entities specific to > particular project to > generate documentation for this project. > Because of problems with entities and xxe we > started to consider to > use <xincude> for this task too. Moreover > <xinclude> offers us a few > nice features which add more flexibility to > documentation customization. > For example keeping project customization in one > XML file instead of > in a few entities files (some entity values have > to be kept in separate files > i. e. longer license note, structural list of > developers). > > Maybe there is some better option for this about > you know... > > # So the problem is: XML documents > customization... There is no simple answer. If there was everyone would be doing it. We are faced with challenges. That's what I like about the project. My only concern is that the move to XInclude was prompted because of an Editor (XXE) that is broken. If it was made at a time when tools like Xerces, Saxon, Xalan etc had support for it. I don't think it would be a problem. The fact today is that only xsltproc supports XInclude. My think tells me. If it's not broken, then don't fix it. ENTITY methods work. XXE does not. Yes XInclude is the <emphasis>future</emphasis>. But it is not yet the <emphasis>now</emphasis>. So if you ask, "What should be in a release?" I say ENTITIES. Lets give XInclude some time. > > Final note: it is good to know that my solution is > not good, have some > limitations or it is not standard, however I can > switch to another approach > if only there is any better one. Many things we are > doing here are not > standard just because this is partially new area and > probably we have > to set a few new standards. > The problem is not your solution. It works. I just think that we should be careful how we address things. Most of the authors I know are not technical. Give them ANT and they get a blank look in their eyes. Talk MAVEN and they fall asleep. Tell them they must run a sh or a bat from the command prompt and they laugh at you. They have been using commercial tools like Word, RoboHelp, HDK etc. to do their authoring. They are, as you said before more comfortable in a WYSIWYG tool. Many feel that editing in the source is taking a step backwards in time. All these years they have dreamed of the perfect WYSIWYG tool, no we want to take it away from them. Do we set a standard. In some respects yes. In others no. When it comes to tools and their technological functionality. I think NO. When it comes to a Framework that works with most Publishing Models, I think YES. Where I think GenerGuide can help is to provide, not only the framework, but also tools or an application that addresses the weaknesses present in the tool chain and XML Editors. Start with automation of command line tasks using GUI. Then authors will be happy to use GenerGuide. Don't ask them to run ANT, MAVEN and a hold suite of other applications. The tool chain is mind blowing enough for them. Look forward to you response. Sean Wheller __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
54 messages has been excluded from this view by a project administrator.
