the said autodocs fail to build. I don't have the exact error available now, but it claims it cannot move the GL chapter after merging all the chapters before it.
For the traditional manual. Yes, I've seen it but have not had the time to find out why. Or gathered the will, is perhaps closer to reality, since the autodoc assembler is about the most hairy code I've written, besides the emit tag.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 20:06: Subject: Autodocs in the latest 7.3
the said autodocs fail to build. I don't have the exact error available now, but it claims it cannot move the GL chapter after merging all the chapters before it.
/ Marek Habersack (Grendel)
I'd be glad to help you in fixing it, as I cannot build the debs because of it, but I'm afraid I have no comb for that hairy code you mentioned :-). Btw, how hard/easy would it be to make the generated docs validate and could I get the refdoc/structure/{modref,onepage}.xml specs anywhere?
/ Marek Habersack (Grendel)
Previous text:
2002-10-18 20:16: Subject: Autodocs in the latest 7.3
For the traditional manual. Yes, I've seen it but have not had the time to find out why. Or gathered the will, is perhaps closer to reality, since the autodoc assembler is about the most hairy code I've written, besides the emit tag.
/ Martin Nilsson (Fake Build Master)
It is not possible to validate the XML used by the autodoc system, due to limitations in DTDs and DTD-compositioning. The XML-files generated from source code comments uses an XML format that is not possible to write a DTD for. The "editorial" parts of the manual are written in a subset of this XML language that is possible to make a DTD for. The description file that describes how to put things to gether into a manual is written in a completely different XML langauge for which a fully descriptive DTD can not be made. A good try is however available in refdoc/structure/structure.dtd with comments about the additional constraints. Finally everything is mashed together into one big XML-file for every manual, which is a composit of all the mentioned XML languages without using XML namespaces.
The question is not why we are stupid enough to defy w3c's shining specs. The question is why w3c makes unusable specs.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 20:18: Subject: Autodocs in the latest 7.3
I'd be glad to help you in fixing it, as I cannot build the debs because of it, but I'm afraid I have no comb for that hairy code you mentioned :-). Btw, how hard/easy would it be to make the generated docs validate and could I get the refdoc/structure/{modref,onepage}.xml specs anywhere?
/ Marek Habersack (Grendel)
Is it possible to write a dtd for a superset?
/ Martin Stjernholm, Roxen IS
Previous text:
2002-10-18 20:31: Subject: Autodocs in the latest 7.3
It is not possible to validate the XML used by the autodoc system, due to limitations in DTDs and DTD-compositioning. The XML-files generated from source code comments uses an XML format that is not possible to write a DTD for. The "editorial" parts of the manual are written in a subset of this XML language that is possible to make a DTD for. The description file that describes how to put things to gether into a manual is written in a completely different XML langauge for which a fully descriptive DTD can not be made. A good try is however available in refdoc/structure/structure.dtd with comments about the additional constraints. Finally everything is mashed together into one big XML-file for every manual, which is a composit of all the mentioned XML languages without using XML namespaces.
The question is not why we are stupid enough to defy w3c's shining specs. The question is why w3c makes unusable specs.
/ Martin Nilsson (Fake Build Master)
One of the current problems with the autodoc XML language is tags with different requirements in different scopes. Putting the definition in a superset doesn't solve that.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 20:38: Subject: Autodocs in the latest 7.3
Is it possible to write a dtd for a superset?
/ Martin Stjernholm, Roxen IS
Well, it would solve the problem of having a dtd that successfully verifies all valid files, wouldn't it?
/ Martin Stjernholm, Roxen IS
Previous text:
2002-10-18 20:43: Subject: Autodocs in the latest 7.3
One of the current problems with the autodoc XML language is tags with different requirements in different scopes. Putting the definition in a superset doesn't solve that.
/ Martin Nilsson (Fake Build Master)
The problem is not to write a DTD that verifies all valid files. The problem is to write a DTD that finds all invalid files.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 20:48: Subject: Autodocs in the latest 7.3
Well, it would solve the problem of having a dtd that successfully verifies all valid files, wouldn't it?
/ Martin Stjernholm, Roxen IS
That's not possible anyway; I'm certain that I'm able to spot errors and inconsistencies that would pass even the most complex verification tool. To make this particular verification tool useable, it's necessary to have a dtd that accepts a superset, the smaller the better. A dtd which only accepts a subset (perhaps along with some comments of how it's necessary to amend its shortcomings) is clearly useless for verification.
/ Martin Stjernholm, Roxen IS
Previous text:
2002-10-18 21:03: Subject: Autodocs in the latest 7.3
The problem is not to write a DTD that verifies all valid files. The problem is to write a DTD that finds all invalid files.
/ Martin Nilsson (Fake Build Master)
The confusion is in our use of the word superset and subset I think.
Yes, it is possible to create a DTD that verifies a superset that includes the set of all valid autodoc XML files. Preferable making the superset as small as possible by altering the autodoc XML format along the way...
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 21:15: Subject: Autodocs in the latest 7.3
That's not possible anyway; I'm certain that I'm able to spot errors and inconsistencies that would pass even the most complex verification tool. To make this particular verification tool useable, it's necessary to have a dtd that accepts a superset, the smaller the better. A dtd which only accepts a subset (perhaps along with some comments of how it's necessary to amend its shortcomings) is clearly useless for verification.
/ Martin Stjernholm, Roxen IS
I don't understand your last sentence.
The difference is perhaps that I consider such a superset-dtd to still be of some use, or at least be better than saying "no, it's not possible to write a dtd for this".
/ Martin Stjernholm, Roxen IS
Previous text:
2002-10-18 21:25: Subject: Autodocs in the latest 7.3
The confusion is in our use of the word superset and subset I think.
Yes, it is possible to create a DTD that verifies a superset that includes the set of all valid autodoc XML files. Preferable making the superset as small as possible by altering the autodoc XML format along the way...
/ Martin Nilsson (Fake Build Master)
The last sentece means; While creating the superset DTD one could alter the XML as is needed to make the superset as close to an actual DTD as possible.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 21:31: Subject: Autodocs in the latest 7.3
I don't understand your last sentence.
The difference is perhaps that I consider such a superset-dtd to still be of some use, or at least be better than saying "no, it's not possible to write a dtd for this".
/ Martin Stjernholm, Roxen IS
Ok. But wouldn't that have a negative impact on the format? From 9194231 I gathered that there are good reasons, and not just clumsy design, behind it being the way it is.
/ Martin Stjernholm, Roxen IS
Previous text:
2002-10-18 21:45: Subject: Autodocs in the latest 7.3
The last sentece means; While creating the superset DTD one could alter the XML as is needed to make the superset as close to an actual DTD as possible.
/ Martin Nilsson (Fake Build Master)
Some of it is clumsy design, but not all. Esp. not the composition parts, eg. not using namespaces during composition, is deliberatly ignorant to the w3c way of things.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 21:50: Subject: Autodocs in the latest 7.3
Ok. But wouldn't that have a negative impact on the format? From 9194231 I gathered that there are good reasons, and not just clumsy design, behind it being the way it is.
/ Martin Stjernholm, Roxen IS
I think the gist of the last sentence is this:
Consider to different contexts where a particular syntactic construct is used. The valid uses in the two contexts might be represented by two vectors U1 and U2:
U1 ^ - - - - - | | | A1 | | | .----------> U2
Now, since the DTD is context free, it has to allow the convex hull (here repesented by the area A1) in order to allow both U1 and U2. Clearly, this superset is much larger than the desired set (containing only U1 and U2).
If the uses U1 and U2 in the different contexts can somehow be brought _closer_ to each other, we can end up with something like this:
_U1' /| / -->U2' /A'-- / -- .--
Now A' is much smaller, and we have achieved a smaller (more optimal) superset just by changing our language a bit.
/ Marcus Comstedt (ACROSS) (Hail Ilpalazzo!)
Previous text:
2002-10-18 21:31: Subject: Autodocs in the latest 7.3
I don't understand your last sentence.
The difference is perhaps that I consider such a superset-dtd to still be of some use, or at least be better than saying "no, it's not possible to write a dtd for this".
/ Martin Stjernholm, Roxen IS
Thanks for the graphic enhancement of my statement.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 21:57: Subject: Autodocs in the latest 7.3
I think the gist of the last sentence is this:
Consider to different contexts where a particular syntactic construct is used. The valid uses in the two contexts might be represented by two vectors U1 and U2:
U1 ^ - - - - - | | | A1 | | | .----------> U2Now, since the DTD is context free, it has to allow the convex hull (here repesented by the area A1) in order to allow both U1 and U2. Clearly, this superset is much larger than the desired set (containing only U1 and U2).
If the uses U1 and U2 in the different contexts can somehow be brought _closer_ to each other, we can end up with something like this:
_U1' /| / -->U2' /A'-- / -- .--Now A' is much smaller, and we have achieved a smaller (more optimal) superset just by changing our language a bit.
/ Marcus Comstedt (ACROSS) (Hail Ilpalazzo!)
I guess there've been a misunderstanding due to my wording - I was asking about the generated HTML documents - they do not validate with the w3c validator and having the autodoc system generate valid HTML shouldn't be that much of a problem.
/ Marek Habersack (Grendel)
Previous text:
2002-10-18 20:31: Subject: Autodocs in the latest 7.3
It is not possible to validate the XML used by the autodoc system, due to limitations in DTDs and DTD-compositioning. The XML-files generated from source code comments uses an XML format that is not possible to write a DTD for. The "editorial" parts of the manual are written in a subset of this XML language that is possible to make a DTD for. The description file that describes how to put things to gether into a manual is written in a completely different XML langauge for which a fully descriptive DTD can not be made. A good try is however available in refdoc/structure/structure.dtd with comments about the additional constraints. Finally everything is mashed together into one big XML-file for every manual, which is a composit of all the mentioned XML languages without using XML namespaces.
The question is not why we are stupid enough to defy w3c's shining specs. The question is why w3c makes unusable specs.
/ Martin Nilsson (Fake Build Master)
Ah. Well the html is produced by make_html.pike, so that's where you'll want to fix things. Beware though that just because the w3c validator gives you a green light doesn't mean that the pages will work with the most number of browsers, or at all.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 21:28: Subject: Autodocs in the latest 7.3
I guess there've been a misunderstanding due to my wording - I was asking about the generated HTML documents - they do not validate with the w3c validator and having the autodoc system generate valid HTML shouldn't be that much of a problem.
/ Marek Habersack (Grendel)
I'm aware of that, but at least HTML validated by w3c gives us a starting point when talking to people who moan that their favorite browser doesn't render something correctly. Please take a look at http://caudium.net/ - it's a good example of a page that looks good in the modern browsers while it validates with the w3c validator - the only sections not being validated now are the pike autodocs and the caudium autodocs (which use the Pike autodocs system, slightly modified for our purpose).
/ Marek Habersack (Grendel)
Previous text:
2002-10-18 21:43: Subject: Autodocs in the latest 7.3
Ah. Well the html is produced by make_html.pike, so that's where you'll want to fix things. Beware though that just because the w3c validator gives you a green light doesn't mean that the pages will work with the most number of browsers, or at all.
/ Martin Nilsson (Fake Build Master)
I tend to take complaints from people who is unable to see pages in their browser serious. My main reason for having pages w3c-validated is to avoid mails from helpful people who finds it their duty to point out that some pages didn't validate succssfully. You can solve this by writing your own DTD and use that one as document type. You get pages that can be validated and you still have the freedom to use old attributes and tags that are required to get really old browsers to do what you want.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 21:54: Subject: Autodocs in the latest 7.3
I'm aware of that, but at least HTML validated by w3c gives us a starting point when talking to people who moan that their favorite browser doesn't render something correctly. Please take a look at http://caudium.net/ - it's a good example of a page that looks good in the modern browsers while it validates with the w3c validator - the only sections not being validated now are the pike autodocs and the caudium autodocs (which use the Pike autodocs system, slightly modified for our purpose).
/ Marek Habersack (Grendel)
aren't you overreacting a bit? I didn't complain - I asked whether it would be hard/easy to fix the validation problems. You are the one who knows the code, not me and, trust me, if I knew what to do I wouldn't ever bother you and waste your precious time with complaints.
/ Marek Habersack (Grendel)
Previous text:
2002-10-18 22:35: Subject: Autodocs in the latest 7.3
I tend to take complaints from people who is unable to see pages in their browser serious. My main reason for having pages w3c-validated is to avoid mails from helpful people who finds it their duty to point out that some pages didn't validate succssfully. You can solve this by writing your own DTD and use that one as document type. You get pages that can be validated and you still have the freedom to use old attributes and tags that are required to get really old browsers to do what you want.
/ Martin Nilsson (Fake Build Master)
I'm not talking about you. I was webmaster for www.d.lintek.liu.se for two years a few years back and got some strange mails. It was actually because of that (not the mails) I was hired by Roxen.
/ Martin Nilsson (Fake Build Master)
Previous text:
2002-10-18 22:37: Subject: Autodocs in the latest 7.3
aren't you overreacting a bit? I didn't complain - I asked whether it would be hard/easy to fix the validation problems. You are the one who knows the code, not me and, trust me, if I knew what to do I wouldn't ever bother you and waste your precious time with complaints.
/ Marek Habersack (Grendel)
ok, my apologies :)
/ Marek Habersack (Grendel)
Previous text:
2002-10-18 22:40: Subject: Autodocs in the latest 7.3
I'm not talking about you. I was webmaster for www.d.lintek.liu.se for two years a few years back and got some strange mails. It was actually because of that (not the mails) I was hired by Roxen.
/ Martin Nilsson (Fake Build Master)
pike-devel@lists.lysator.liu.se
-
Marcus Comstedt (ACROSS) (Hail Ilpalazzo!) ＠ Pike (-) developers forum -
Marek Habersack (Grendel) ＠ Pike (-) developers forum
-
Martin Nilsson (Fake Build Master) ＠ Pike (-) developers forum
-
Martin Stjernholm, Roxen IS ＠ Pike developers forum