After some requests in gentoo-dev mailing list, I finally got some time to work in a guide to build project pages using projectXML. I wanted to write something not very heavy: a basic section with the most usual info for those who need a quick page and another extended section which cover the advanced features allowed by projectXML. More or less I've structured the sections this way: * Creating a project page (the basic info) - general data - goals - devs - herds - resources * Tweaking the project page (advanced) - extrachapters - subprojects - tasks There are probably too many grammar errors waiting out there, please feel free to fix them. Any comments, feedback or destructive criticism is very welcome. Thanks.
Created attachment 124442 [details] projectxml.xml Original guide in guidexml format. An online version can be found in: http://dev.gentoo.org/~yoswink/tmp/projectxml.xml
Not really a docs-team bug, but I don't know whom to reassign to. There's one already: http://www.gentoo.org/proj/en/metastructure/projectxml.xml Will yours replace that one? BTW, "It [projectXML] uses the same XML style that <uri link="/doc/en/xml-guide.xml">guidexml doc</uri>" is not quite true. It uses an invalid guideXML spec, generates invalid GuideXML which in turn generates invalid HTML. You might want to fix that first. See bug #128615. I can fix the DTD/XSL so that only valid GuideXML gets generated, but I shall not fix the project pages that will be affected.
(In reply to comment #2) > Not really a docs-team bug, but I don't know whom to reassign to. Neither do I. I just assigned to docs-team for review, comments and fixes. Probably I'll ask devrel or council if we don't have a better option. > > There's one already: http://www.gentoo.org/proj/en/metastructure/projectxml.xml > Will yours replace that one? I think this new one is a friendly approach while the previous was quite based on explaining the DTD and can be a bit hard for some people. I've included examples and structured the doc to be easy to read. Both seems to have the same objective so probably we should leave only one. > > BTW, "It [projectXML] uses the same XML style that <uri > link="/doc/en/xml-guide.xml">guidexml doc</uri>" is not quite true. > It uses an invalid guideXML spec, generates invalid GuideXML which in turn > generates invalid HTML. > You might want to fix that first. See bug #128615. I can fix the DTD/XSL so > that only valid GuideXML gets generated, but I shall not fix the project pages > that will be affected. > I can take care of project pages to transform the longdescription section to be: or just plain text or a guidexml block beggining with <p> (if I didn't understand bad the bug #128615). After that, I will pacth this doc to mention both possibilities.
(In reply to comment #3) > > There's one already: http://www.gentoo.org/proj/en/metastructure/projectxml.xml > > Will yours replace that one? > > I think this new one is a friendly approach while the previous was quite based > on explaining the DTD and can be a bit hard for some people. I've included > examples and structured the doc to be easy to read. Both seems to have the same > objective so probably we should leave only one. Agreed. Just overwrite it. > I can take care of project pages to transform the longdescription section to > be: or just plain text or a guidexml block beggining with <p> (if I didn't > understand bad the bug #128615). After that, I will pacth this doc to mention > both possibilities. You don't get both because it cannot be expressed in a DTD and the objective is to have valid projectXML generate valid GuideXML. Having three various copies of GuideXML DTD is not clever (project/guide/book). Besides, the copy used in projectXML is outdated and allows a big mix of everything (%all.class;), e.g. <p> inside inline elements... I have edited the DTDs so that the common stuff is shared from a single file. This invalidated ca. 80 project pages, all fixed (xmlcopyeditor++) except a couple of translations. I diffed the list of all invalid files before and after my changes: ./news/ru/gwn/template-newsletter.xml ./proj/es/base/x86/at.xml ./proj/es/hardened/index.xml ./proj/es/hardened/rsbac/index.xml ./proj/pl/hardened/selinux/index.xml ./proj/ro/releng/catalyst/index.xml ./proj/ru/glep/index.xml Files that were invalid before my changes are still invalid. The new DTD is based on current usage and what becomes of the data in the XSL, e.g. <longdescription> and <goals> are processed like <body> and some project pages used several block elements, therefore they share the same definition, i.e. they have to wrap text inside <p>. Now, you have to edit your doc :) The DTD is easier to read IMHO, but if you need help, just ask.
./proj/ru/glep/index.xml is fixed. ./news/ru/gwn/template-newsletter.xml will be fixed or removed as soon as new GWN will be out. In any case this document is not linked anywhere on the site and is kept only for our local reference.
> > I have edited the DTDs so that the common stuff is shared from a single file. > This invalidated ca. 80 project pages, all fixed (xmlcopyeditor++) except a > couple of translations. > Yay! > I diffed the list of all invalid files before and after my changes: > ./proj/es/base/x86/at.xml > ./proj/es/hardened/index.xml > ./proj/es/hardened/rsbac/index.xml /es/ fixed. I will ping alin and rane to fix the rest. > > Now, you have to edit your doc :) > The DTD is easier to read IMHO, but if you need help, just ask. > Easy enough. A new attachment is on the way. Thanks.
Created attachment 125133 [details] project.xml Add notes about the special guidexml syntax in longdescription, goals and extrachapters. Fixed the examples according with it.
(In reply to comment #6) > > /es/ fixed. I will ping alin and rane to fix the rest. Since alin seems not to be available (nighmorph dixit), I had fixed /ro/ so only rane is missing.
Some suggestions: . Be consistent and please use GuideXML & ProjectXML . Place <> around tag names, e.g. <c><name></c> . You use GuideXML block instead of <body>. "GuideXML block" does not mean anything and I doubt anyone would be familiar with what we call block elements. IMO, <longdescription> and <goals> would be better described if you just said they <e>must</e> contain one or more paragraphs (<c><p></c>), tables, lists, code samples, admonitions (<note>/<warn>/<impo>). The simplest case being a single <p> element. . Why not link to herds.xml instead of using <path>herds.xml</path> ? . <resource link="/internal/gentoo/link.xml"> IMO it's not clear "internal gentoo link" means local link, just mention "http://www.gentoo.org" can be omitted. . "The <c>extrachapter</c> uses a section structure" is wrong. It uses a chapter structure. An extrachapter becomes a GuideXML chapter and must have the same structure: it may have one <title> and must have one or more <section>. Each section may have a <title> and must have one or more <body>. Each <body> must have one ore more paragraphs, code samples, tables, lists, admonitions. . s/tag, we have to reflect these other xml labels/element, you must specify the following elements/ and a few more English fixes. . You might want to explain how to get a project linked from /proj/en/index.xml Thanks for taking the time to write this document.
(In reply to comment #9) > Some suggestions: > > . Be consistent and please use GuideXML & ProjectXML Done. > > . Place <> around tag names, e.g. <c><name></c> Done in all places except inside <pre> blocks. > > . You use GuideXML block instead of <body>. "GuideXML block" does not mean > anything and I doubt anyone would be familiar with what we call block elements. > IMO, <longdescription> and <goals> would be better described if you just said > they <e>must</e> contain one or more paragraphs (<c><p></c>), tables, > lists, code samples, admonitions (<note>/<warn>/<impo>). The simplest case > being a single <p> element. Much better, I didn't know how to express it in an easy way. Done. > . Why not link to herds.xml instead of using <path>herds.xml</path> ? Done. > . <resource link="/internal/gentoo/link.xml"> IMO it's not clear > "internal gentoo link" means local link, just mention "http://www.gentoo.org" > can be omitted. Ok, done. > . "The <c>extrachapter</c> uses a section structure" is wrong. It uses a > chapter structure. An extrachapter becomes a GuideXML chapter and must have the > same structure: it may have one <title> and must have one or more <section>. > Each section may have a <title> and must have one or more <body>. Each <body> > must have one ore more paragraphs, code samples, tables, lists, admonitions. > > . s/tag, we have to reflect these other xml labels/element, you must specify > the following elements/ > and a few more English fixes. rephrased, I hope now is clearer. > > . You might want to explain how to get a project linked from /proj/en/index.xml Added a final chapter about this. > > Thanks for taking the time to write this document. > Thanks for taking yours to review.
Created attachment 125276 [details] projectxml.xml New version with all the neysx's suggestions. On-line version: http://dev.gentoo.org/~yoswink/tmp/projectxml.xml Diff against previous: http://dev.gentoo.org/~yoswink/tmp/projectxml.diff
(In reply to comment #4) > (In reply to comment #3) > > > There's one already: http://www.gentoo.org/proj/en/metastructure/projectxml.xml > > > Will yours replace that one? > > > > I think this new one is a friendly approach > > Both seems to have the same > > objective so probably we should leave only one. > Agreed. Just overwrite it. ^^^
(In reply to comment #12) > (In reply to comment #4) > > (In reply to comment #3) > > > > There's one already: http://www.gentoo.org/proj/en/metastructure/projectxml.xml > > > > Will yours replace that one? > > > > > > I think this new one is a friendly approach > > > Both seems to have the same > > > objective so probably we should leave only one. > > > Agreed. Just overwrite it. > > ^^^ > Done. Thanks Xavier.
