Menu
▾
▴
generguide-devel
|
From: Cameron S. <ca...@sh...> - 2003-09-11 11:46:07
|
Hi, Sean has made me think about the scope and direction of the generguide project a bit. In particular, are we limiting ourselves by focusing generguide on "Business Processes"? Are there other forms of documentation that would benefit from this modular approach? Sean, do you have one or two examples? If so, then it may be appropriate to split the generguide into 2 projects: 1. Just the tools to process modular documentation, along with any standards or convensions we need to enforce. 2. The text of the Software Developers Guide. In future, other purely documentation projects can spring up independantly of generguide (except that it uses the generguide tools). For want of a better word, these projects could be called GenerRepositories. GenerRepositories can reference each other in a similar manner to web pages referencing each other. This leads me onto our developement path. Here is what I see needs doing: 1. Develop a generconfig web editing tool. (Done by me for filtering sections). 2. Get publishing working within maven. Not essential since we have the unix scripts which work (generpublish.sh), but it would be nice to have. Artur, have you been working on this? If so, how is it going? 3. Define variables (like entities) within generconfig so that they can be used within XXE editor. I plan to work on this next. 4. Incororate variable editing in the generconfig web editing tool. <Release 0.3alpha> 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. 6. Incorporate into generconfig web editing tool. <Release 1.0beta> ??? ------- Have I missed anything? Sean, I assume you will have ideas I have not thought of. Am I on the right track? At what point should we annonce this project to related email lists in order to attract attention? -- 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-11 14:40:39
|
Hi,
I try to introduce now generguides in my company. At the time of doing this
I came across a few problems. They are not difficult to solve, the more
I am member of generguide team, but they are a little bit annoying.
They can be more annoying for someone completely new to this idea.
So I think they should be solved in some way, before alpha release.
1. Working with documents on windows. I am talking about generpublish
script. For many windows users it is not easy to accept they need to
install something like cygwin to generate target formats of documentation.
So providing any, even simple and basic, tools for windows+java is
essential. However due to windows command line limitation I think
that can be simpler to create good maven support than writing some kind
of generpublish.bat script.
2. Commented entities are difficult to work with, but it is closely associated
with above windows limitation. However as I remember we were talking about
change them to <xinclude> elements. Are we ready to do it?
3. I had to create separate document about development tools and another
about development conventions. But this two issues are not well separated
in our guides set. It is not essential for alpha or even no. 1 release, but it would
be good to think about writing sections targeting only one issue. So we have
much more flexibility during building final document.
4. No documentation how to use it. I mean how to use configuration files and how
to set them up.
> If so, then it may be appropriate to split the generguide into 2 projects:
> 1. Just the tools to process modular documentation, along with any standards
> or convensions we need to enforce.
> 2. The text of the Software Developers Guide.
Yes, that is good idea for splitting project into parts, however details are not
clear for me yet.
> This leads me onto our developement path.
> Here is what I see needs doing:
> 1. Develop a generconfig web editing tool. (Done by me for filtering
> sections).
Yes, it is very important in my opinion.
> 2. Get publishing working within maven. Not essential since we have the unix
> scripts which work (generpublish.sh), but it would be nice to have. Artur,
> have you been working on this? If so, how is it going?
It seems to that it is also very important to target wider developers community.
I still work on this, however I contantly come across problems with implementation
details which block me from finishing it, like xalan+JDK1.4, xpointer implementation
in xalan and saxon, and many small things which seems not very important but they
make maven suuport almost useless.
I can see now, it is not good that I try to implement all features at once. I should
release first version first, which have some limited support but works for basic cases
and than try to extend it with next features.
So I will try to prepare first basic maven plugin for sdocbook, which support
simple modular documentation in next few days.
> 3. Define variables (like entities) within generconfig so that they can be
> used within XXE editor. I plan to work on this next.
Does it mean you want to replace entities with <xinclude> elements?
> 4. Incororate variable editing in the generconfig web editing tool.
> <Release 0.3alpha>
Could you say what you mean when you are talking about 'variables'
please at last a few words to ensure me that we are thinking about the same.
> 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.
> Have I missed anything? Sean, I assume you will have ideas I have not thought
> of. Am I on the right track?
> At what point should we annonce this project to related email lists in order
> to attract attention?
I think we definitely need users to see if we are going in right direction.
At least we should be first users to ensure that it is useful what we are providing.
I try to introduce this in my company, however we are going to implement
extreme programming idea and documentation issue is not that important.
So it will not be used extensivelly.
But generguide project should use itself tools which it provide. So at least
we, in generguide project, should be first users. And I think we will be ready
to release any version if whole project documentation will be generated
with use of our tools.
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-12 05:55:31
|
--- Artur Hefczyc <ko...@pl...> wrote: [snip] Implementation Problems > > 1. Working with documents on windows. I am talking > about generpublish > script. For many windows users it is not easy to > accept they need to > install something like cygwin to generate target > formats of documentation. > So providing any, even simple and basic, tools > for windows+java is > essential. However due to windows command line > limitation I think > that can be simpler to create good maven support > than writing some kind > of generpublish.bat script. I think that requirements need to be defined that will address portability. > 2. Commented entities are difficult to work with, > but it is closely associated > with above windows limitation. However as I > remember we were talking about > change them to <xinclude> elements. Are we ready > to do it? ENTITY Management can be part automated. See my explanation at this link http://www.oxygenxml.com/forum/viewtopic.php?t=156 <xi:include> is still a problem. Most tools like xalan only have an experimental implementation. For parsing the same applies, see this link http://xml.apache.org/xerces2-j/faq-xinclude.html ENTITY reference and xinclude need to be supported. First because of the above and second to provide backward compatibility to all the legacy out there. > 3. I had to create separate document about > development tools and another > about development conventions. But this two > issues are not well separated > in our guides set. It is not essential for alpha > or even no. 1 release, but it would > be good to think about writing sections > targeting only one issue. So we have > much more flexibility during building final > document. The problem is deciding on what level of granularity to apply to the modular concept. I will put together an article on this subject. It may serve as food for debate that may result in some recommendations. I say recommendations, because I think that granularity is not 100% under our control. > 4. No documentation how to use it. I mean how to use > configuration files and how > to set them up. Yes, a Generguide User Manual would be good. I will start working on this, but I am also just beginning to find out how all the parts hang together. > > If so, then it may be appropriate to split the > generguide into 2 projects: > > 1. Just the tools to process modular > documentation, along with any standards > > or convensions we need to enforce. > > 2. The text of the Software Developers Guide. > Yes, that is good idea for splitting project into > parts, however details are not > clear for me yet. It is very wise to create a high-level guideline/recommendation (the technique) and then have application specific projects. The guideline should be as generic possible to ensure scalability across applications (projects). Application examples include: 1. User Manuals for Software 2. User Manuals for Hardware 3. Product Descriptions 4. Reference Guides 5. Training Materials 6. Application Notes 7. White Papers 8. Tenders 9. Management Documents (ISO, PRINCE2, RUP etc) 10. 11. the list is long .. [snip] generconfig web editing tool. > > 2. Get publishing working within maven. Not > essential since we have the unix > > scripts which work (generpublish.sh), but it would > be nice to have. Artur, > > have you been working on this? If so, how is it > going? > It seems to that it is also very important to target > wider developers community. > I still work on this, however I constantly come > across problems with implementation > details which block me from finishing it, like > xalan+JDK1.4, xpointer implementation > in xalan and saxon, and many small things which > seems not very important but they > make maven support almost useless. Scripts or utils provided must be portable. > I can see now, it is not good that I try to > implement all features at once. [snip] > > > 3. Define variables (like entities) within > generconfig so that they can be > > used within XXE editor. I plan to work on this > next. > Does it mean you want to replace entities with > <xi:include> elements? Again, xi:include is experimental. So it should be in generguide. [snip] > > 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 > locally. > They can be kept locally to speed processing up, but > main reference should > be to source location. > > > Have I missed anything? Sean, I assume you will > have ideas I have not thought > > of. Am I on the right track? 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. > > At what point should we announce this project to > related email lists in order > > to attract attention? > I think we definitely need users to see if we are > going in right direction. > At least we should be first users to ensure that it > is useful what we are providing. The more help the better. On the downside, without a stable recommendation, it will be chaos. __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Artur H. <ko...@pl...> - 2003-09-12 10:30:27
|
Hi, see comments inline. > > essential. However due to windows command line > > limitation I think > > that can be simpler to create good maven support > > than writing some kind > > of generpublish.bat script. > I think that requirements need to be defined that will > address portability. Yes, you are absolutely right. However I can't see the only one right solution and approach. Software projects have been developing on so many platforms and environments that I am afraid there is no only one solution. I think that we end up with at least a few scripts for the most important systems and environments, like windows, unix, ant, maven, cgi script - suggested by Cameron and maybe some more. The most general is cgi script, but it has limitations too. > > 2. Commented entities are difficult to work with, > > but it is closely associated > > with above windows limitation. However as I > > remember we were talking about > > change them to <xinclude> elements. Are we ready > > to do it? > ENTITY Management can be part automated. See my > explanation at this link > http://www.oxygenxml.com/forum/viewtopic.php?t=156 I was talking about our style of entities use. They are placed in documents in special kind of comments. And these comments are removed during processing XML files. It is easy to accomplish this on Linux, but difficult on windows due to lack of sed, grep and very poor scripting language. We use entities for project customization. For example when document describes CVS repository location we use entitiy &cvs_url; and in configuration file we can set proper url for particular project without modifying XML file. So we have fully reusable documentation modules. However entities cause some problems with editing tools like xxe. To work around this we have temporally put them in comments. The proper solution is to change XML editing tools or replace entities with something different. There is no good and free replacement for xxe, but we have found a way to efficiently work with <xinclude> elements. As you have writen there is no good parser and processor for <xinclude> yet. But Cameron found xinclude.xsl which works very well for most basic <xinclude> cases. And it require only any good XSL processor to use such as xalan, saxon, or even xslproc (which has <xicnlude> support builtin indeed). > <xi:include> is still a problem. Most tools like xalan > only have an experimental implementation. For parsing > the same applies, see this link > http://xml.apache.org/xerces2-j/faq-xinclude.html > > ENTITY reference and xinclude need to be supported. > First because of the above and second to provide > backward compatibility to all the legacy out there. See my above, comments. > The problem is deciding on what level of granularity > to apply to the modular concept. I will put together > an article on this subject. It may serve as food for > debate that may result in some recommendations. I say Great!, maybe we will decide to make an IRC meeting for this purpose. > Application examples include: > 1. User Manuals for Software > 2. User Manuals for Hardware > 3. Product Descriptions > 4. Reference Guides > 5. Training Materials > 6. Application Notes > 7. White Papers > 8. Tenders > 9. Management Documents (ISO, PRINCE2, RUP etc) > 10. > 11. the list is long .. Yes, that's good idea. 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-12 12:37:33
|
--- Artur Hefczyc <ko...@pl...> wrote: > > > essential. However due to windows command > line > > > limitation I think > > > that can be simpler to create good maven > support > > > than writing some kind > > > of generpublish.bat script. > > I think that requirements need to be defined that > will > > address portability. > Yes, you are absolutely right. However I can't see > the only one > right solution and approach. Software projects have > been developing > on so many platforms and environments that I am > afraid there is > no only one solution. > I think that we end up with at least a few scripts > for the most important > systems and environments, like windows, unix, ant, > maven, > cgi script - suggested by Cameron and maybe some > more. > > The most general is cgi script, but it has > limitations too. Other than standardizing on JAVA and programming the functionality of any scripting into the app, I don't think that there is a standard solution. If the route is to dev an app that performs the operations, then it will be easy for most users to start using generguide. In addition, it could serve as a plug-in to a number of other Java based editors jedit, oxygen, XXE, Morphon etc. This would obviate the need for people to have to learn another editor. The learning curve will be limited to the Java App. > > > 2. Commented entities are difficult to work > with, > > > but it is closely associated > > > with above windows limitation. However as I > > > remember we were talking about > > > change them to <xinclude> elements. Are we > ready > > > to do it? > > ENTITY Management can be part automated. See my > > explanation at this link > > http://www.oxygenxml.com/forum/viewtopic.php?t=156 > I was talking about our style of entities use. They > are placed in > documents in special kind of comments. And these > comments are > removed during processing XML files. It is easy to > accomplish this > on Linux, but difficult on windows due to lack of > sed, grep > and very poor scripting language. > > We use entities for project customization. For > example when document > describes CVS repository location we use entity > &cvs_url; and > in configuration file we can set proper url for > particular project without > modifying XML file. So we have fully reusable > documentation modules. > > However entities cause some problems with editing > tools like xxe. > To work around this we have temporally put them in > comments. > > The proper solution is to change XML editing tools > or replace entities > with something different. > There is no good and free replacement for xxe, but > we have found a > way to efficiently work with <xinclude> elements. > As you have written there is no good parser and > processor for > <xinclude> yet. But Cameron found xinclude.xsl which > works very > well for most basic <xinclude> cases. And it require > only any good > XSL processor to use such as xalan, saxon, or even > xslproc (which > has <xicnlude> support builtin indeed). In my opinion, tools like XXE are broken. The best way to author XML Documents is directly into the source view. The WYSIWYG and Single-Source concepts are on opposite ends of the same boom stick. If you try to bring the end together, the stick will break. CSS views work fine in the document is not modular. Regarding entities. Your application of entities is not standard. Therein is a problem. It is safer to apply standards. In addition, entities have many applications. You may use them for project customization, but others use them to build modular documents. I don't think it wise that generguide's application of entities be limited. As I said before, the scope needs to widen and the recommendation should be more generic. If this is not done then the flexibility of generguide will be limited. > > > <xi:include> is still a problem. Most tools like > xalan > > only have an experimental implementation. For > parsing > > the same applies, see this link > > http://xml.apache.org/xerces2-j/faq-xinclude.html > > > > ENTITY reference and xinclude need to be > supported. > > First because of the above and second to provide > > backward compatibility to all the legacy out > there. > See my above, comments. DITTO > > > The problem is deciding on what level of > granularity > > to apply to the modular concept. I will put > together > > an article on this subject. It may serve as food > for > > debate that may result in some recommendations. I > say > Great!, maybe we will decide to make an IRC meeting > for > this purpose. > > > Application examples include: > > 1. User Manuals for Software > > 2. User Manuals for Hardware > > 3. Product Descriptions > > 4. Reference Guides > > 5. Training Materials > > 6. Application Notes > > 7. White Papers > > 8. Tenders > > 9. Management Documents (ISO, PRINCE2, RUP etc) > > 10. > > 11. the list is long .. > Yes, that's good idea. I am glad you like the idea. I hope that you also realize the implications. If generguides requirements fail to be generic, each of these applications will test their integrity. If any of them break the recommendation, them we will be faced with making changes, rethinking whole concepts. As the number of applications increase, the overhead will also increase. Changes to the recommendation may also violate the integrity of legacy applications, requiring them to be modified to be inlinin-line the new geneguide recommendation. In my vision I see that an application must conform 100% to the recommendation, but that it may have extensions to cater for application specific senscenariosf all applications have a common extension, then it should not be an extension. Rather a part of the core recommendation. This approach will make it much easier for new members to start projects. It will also reduce the learning curve for people wanting to use generguide. Once they understand the core recommendation, they only have to learn the extension for the application(s) they want to use. This is why I stress, standardized approaches and stabilization of the generguide recommendation before work begins on application specific projects. Hope I am not going to far at a tangent. Sean Wheller __________________________________ Do you Yahoo!? Yahoo! SiteBuilder - Free, easy-to-use web site design software http://sitebuilder.yahoo.com |
|
From: Artur H. <ko...@pl...> - 2003-09-12 14:18:16
|
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.
And one another thing. English is not my native language
so please be patient and don't feel offended I have no intention
to do so, it can be just my poor English.
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 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...)
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...
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)...
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.
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...
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.
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...
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.
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-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 |
|
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: 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: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: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: Artur H. <ko...@pl...> - 2003-09-12 09:57:56
|
> > windows+java is essential. However due to windows command line limitation I > > think that can be simpler to create good maven support than writing some > > kind of generpublish.bat script. > Agreed. Are you working on this? I created very simple windows script for geotools project and I think I can generalize it for generguide needs a little bit after first release of maven plugin. > Another option is to put the generpublish.sh script inside a CGI wrapper and > make it accessable via the web. > Ie: Allow user to upload a generconfig.xml file, user can then edit the config > file, user can then download the config file, or a zipped Developer's Guide. Yes, I think it is very good idea. It would be the most portable solution. But maybe it is not mandatory for release no. 1.0 > I'm wondering whether we should announce the existance of our project before > we consider it ready to use so that someone else doesn't start a similar > project. Also, by announcing our project early, we may attract developers > and users (like Sean) who can help define what needs to be done, and help us > get there. Yes, I think it can be good move. Users or even quests feedback is the most valuable for our work. Artur -- Artur Hefczyc Open Source Developer http://generguide.sourceforge.net/ http://www.geotools.org/ http://wttools.sourceforge.net/ http://maven-plugins.sourceforge.net/ |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X