I just explain how we used the ALIAS feature in the past.
All dialogs and message boxes have program internal IDs.
This IDs are generated in a special way and finally after a build we get a HTMLDefines.h file that is used in the ALIAS section.
AFAIK you call them map files in your documentation.
The file looks like this
Code: Select all
#define HIDR_MAINFRAME 0x20001
#define HIDW_WORKFLOW_PICKTICKET 0x500C8
#define HID_ACTIVITY_FILTER 0x18002
#define HIDP_ERR_DIALING 0x304AF
Our previous help tool (ROBOHELP) also allowed us to use this .h file and to use the defined human readable IDs inside the program when we create the help topics.
Help&Manual can only use the IDs.
Using Topic IDs as a string (as suggested in another thread herein the forum) isn't possible, because there is no way back from the ID to the defines in our program and it is to much work to reassign every program location a new Topic ID (string).
The documentation team is solely responsible for the Topic ID field: So they are the owner of the information and we (the developer) have no influence it.
Yes we can use the IDs directly. But for us the already existing human readable ID generated in the map file is a perfect description and discussion anchor between the documentation guys and the development. Also it is possible that the development guys renumber their IDs. The names like HIDR_MAINFRAME don't change, they may be deleted or added. Renumbering the resources is a rare case but happens. And in such a case we are lost.
My wish:
Allow a map file to be statically defined in the help project.
Allow the human readable IDs to be selected in the field "Help Context".
Internally in your program change nothing:
If an ID exists in the defined map file for the project, don't show the number, show the human readable key (it is an alias).
If there is no matching ID in the defined map file just show the ID.
This simple solution doesn't help us when the resource IDs are renumbered.
A perfect solution would be:
1. Help&Manual uses our human readable IDs in the "Help Context" field and finally uses our given .h in the ALIAS section when the help file is created.
2. And the context tool will show the already given "human readable alias" defines from the map file.
3. The context tool shows all "human readable defines" from the map file and that are not used/assigned inside the help project.
4. Allow to pick a "human readable alias" from the map file into the "Help Context" field.
At least a good help:
Allow the user to add Help Context IDs in hexadecimal format.
Yes I know that C/C++ programmers are getting less and less, but this is the given infrastructure we receive from Microsoft Visual Studio.
But using such a map file would allow to separate development from writing the online help more easily. An abstract human readable word is the link, und not just a "digit". As a programmer I don't like pure numbers in my code. I prefer symbolic values that finally are replaced by the compiler.
PS: We don't like ROBOHELP. We are still using an old version because it works (sometimes and some how
). But it fits our needs.I just made a second attempt to get Help&Manual into our production cycle.
TIA
