Hello Edson,
your points are very good. It is the skeleton/template we have to define primary. Here I see couple of items you should take in consideration: - ability to generate standalone readme per module and aggregate all in single document. Perhaps here we can have two documets in each module, one that will have the head/tag of a book, and the other, head/tag of a chapter -- they will be very small, just including the other documents. - module names, parameters name, function names, PV names, ..., must be clearly marked so we can extract very easy the index. You did the previous indexes in dokuwiki, and you know better how hard is to do it with the current structure. - the generated html formats should have all the time same anchor for parameters, functions, a.s.o, so that the reference will stay the same, even new elements are introduced. If I am not wrong, that is possible by setting an unique 'id'. In this way, links sent to mailing list, in the indexes, will be persistent over the years.
To my first point, a proposal of files will be - name_book.xml - will have structure of a book and include name.xml - name_chapter.xml - will have structure of a chapter and include name.xml (to investigate whether won't be same as name.xml) - name.xml - similar to what is now name.sgml -- details about author, editor, etc... and include the other files - name_admin.xml - will contain the documentation for administrators -- same as name_users.sgml, just the 'users' is a bit unclear and thought 'admin' might be better - name_devel.xml. and others will be added as needed
Cheers, Daniel
On 02/27/08 01:26, Edson wrote:
Hi, Daniel... Guys...
So let's try to draw a first to-do list, so that the work can begin...
1- Migrate the existing DOCs from SGML to XML format: I'm not a DocBook expert but Henning and I already changed some thoughts on this. What's not clear to me is if this is just a translation matter or also a diagramatic problem? Translation is some kind of direct work, while diagramatic requires a previous discussion.
2- Suppress and/or Agregate new DOCs: Clean-up empty files (with a sort of "no content") is require, since there information can be gatered elsewhere, but agregate new DOCs is a sort of "asking for problems" approach, so I would say that some skeleton/template has to be defined. This has to become before this agregation issue. But this arises a problem: wich is the best 'skeleton'? Which kind of documentation will be present? How to automate it?
So this two points brings: 1- Documentation structure Skeleton/Template; 2- Documents Skeleton/Template defining chapter and, maybe, minimum section contents, definition of origin (directly from code? From Doxygen?) and, most important, responsibilities; 3- XML Style that translate/implement this skeleton/templates; 4- Conversion of actual SGML format to some DocBook-XML format;
Each of this points should define a milestone by itself and its end it could be marked with IRC meeting where the results could be presented and discussed.
Please these are only thoughs... so fell free to add more points and/or point me wrongs approaches.
Edson
-----Original Message----- From: Daniel-Constantin Mierla [mailto:miconda@gmail.com] Sent: terça-feira, 26 de fevereiro de 2008 18:37 To: Edson Cc: openser-docs@lists.openser.org Subject: Re: [OpenSER-Docs] First Clean-up Patch for Documentation
Hello,
On 02/26/08 22:27, Edson wrote:
Hi, Guys...
I finish the first clean-up of the documentation. It consisted by:
- remove all FAQ and DEVEL files considered empty in content (no content at all or just the default lines);
- remove of the <RevHistory>/</RevHistory> tag (and of course anything Between them);
- remove the comments at the EOF that beginned with "<!-- Keep this element at the end of the file";
Thanks, I believe we should think also the context of migrating to xml format. Anybody with some docbook xml experience? Hints, tips? I am investigating now the best way to migrate from sgml to xml.
If we are going to remove some file, add new ones, we need to have in mind the near future as well.
The attached file (in ZIP format) is the resulting SVN DIFF file. It was applied over trunk version, revision 3761.
I would like to ask the developers how much is a good time to wait for comments and revisions before commiting the changes? 1 week? 10 days? Sugestions?
Let's plan kind of to-do list/roadmap, to sync the work and check the milestones. Otherwise many will work on same task, or go totally different direction.
Cheers, Daniel
Edson
Openser-docs mailing list Openser-docs@lists.openser.org http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs