Hello,
first, after reviewing a bit latest changes to module docs, I discovered that we renamed module_user.xml to module_admin.xml, but we forgot about chapter's title, it is still "User's guide". Should we replace it with something more suggestive?
Second, coming to something was a bit touched in past discussions. It is about adding ID attribute to sections and examples. That will help to get persistent links inside a document. The issue is that we have modules with same parameter name, also, perhaps modules with many sections for same function (with different number of parameters), so we should come up with some rules to avoid conflicts.
A pattern can be: - for functions: modulename_f_functionname (plus 1 or 2 if there are many sections for same function) - for parameters: modulename_p_parametername - for mi commands: modulename_mi_commandname - for PVs: modulename_pv_pvname - for the rest of sections: modulename_someuniqueid
In this way we ensure naming space within module. The bad might be that modulename is quite long sometime, alternative will be to allocate an ID per module, but we get to these IDs management, which, makes no sense, in my opinion. In addition, having a clear pattern for ids, will help to write the links by hart, although this is not something that important.
Updates will be done as we go, but we should enforce for new additions.
Any comments?
Cheers, Daniel
On Monday 10 March 2008, Daniel-Constantin Mierla wrote:
first, after reviewing a bit latest changes to module docs, I discovered that we renamed module_user.xml to module_admin.xml, but we forgot about chapter's title, it is still "User's guide". Should we replace it with something more suggestive?
Hi Daniel,
perhaps we can name this 'Admin Guide', or 'Module Reference'? I think it would make sense to replace this with an entity if we change this now, to make further changes easier.
Second, coming to something was a bit touched in past discussions. It is about adding ID attribute to sections and examples. That will help to get persistent links inside a document. The issue is that we have modules with same parameter name, also, perhaps modules with many sections for same function (with different number of parameters), so we should come up with some rules to avoid conflicts.
A pattern can be: [..] In this way we ensure naming space within module. The bad might be that modulename is quite long sometime, alternative will be to allocate an ID per module, but we get to these IDs management, which, makes no sense, in my opinion. In addition, having a clear pattern for ids, will help to write the links by hart, although this is not something that important.
Updates will be done as we go, but we should enforce for new additions.
Sounds good. Some modules uses also a abbreviated form as internal prefix, e.g. 'ul' for usrloc. But for me its fine to use complete module name.
Cheers,
Henning
Hi, Daniel... Henning...
I was thinking about this ID issue... I really could'nt find an alternative, but I have to notice that BIG tags could disencourage documents update.
To avoid this I can think only in a kind of WYSIWYG solution. I didn't find any editor with this capability... maybe You know...
Edson
-----Original Message----- From: openser-docs-bounces@lists.openser.org [mailto:openser-docs- bounces@lists.openser.org] On Behalf Of Henning Westerholt Sent: quarta-feira, 12 de março de 2008 08:34 To: openser-docs@lists.openser.org; miconda@gmail.com Subject: Re: [OpenSER-Docs] module docs: internal anchors
On Monday 10 March 2008, Daniel-Constantin Mierla wrote:
first, after reviewing a bit latest changes to module docs, I discovered that we renamed module_user.xml to module_admin.xml, but we forgot about chapter's title, it is still "User's guide". Should we replace it with something more suggestive?
Hi Daniel,
perhaps we can name this 'Admin Guide', or 'Module Reference'? I think it would make sense to replace this with an entity if we change this now, to make further changes easier.
Second, coming to something was a bit touched in past discussions. It is about adding ID attribute to sections and examples. That will help to get persistent links inside a document. The issue is that we have modules with same parameter name, also, perhaps modules with many sections for same function (with different number of parameters), so we should come up with some rules to avoid conflicts.
A pattern can be: [..] In this way we ensure naming space within module. The bad might be that modulename is quite long sometime, alternative will be to allocate an ID per module, but we get to these IDs management, which, makes no sense, in my opinion. In addition, having a clear pattern for ids, will help to write the links by hart, although this is not something that important.
Updates will be done as we go, but we should enforce for new additions.
Sounds good. Some modules uses also a abbreviated form as internal prefix, e.g. 'ul' for usrloc. But for me its fine to use complete module name.
Cheers,
Henning
Openser-docs mailing list Openser-docs@lists.openser.org http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
-
Daniel-Constantin Mierla -
Edson -
Henning Westerholt