[OpenSER-Docs] module docs: internal anchors

Daniel-Constantin Mierla miconda at gmail.com
Mon Mar 10 13:31:00 CET 2008


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?


More information about the sr-docs mailing list