Generating IDs for navref elements

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
julio
Posts: 118
Joined: Wed May 28, 2008 12:06 am
Location: Porto Alegre, RS - Brasil
Contact:

Generating IDs for navref elements

Unread post by julio »

Hi,

I am currently working on a script to generate documentation for new products. We use an automated process to create all files of a project, that is, a whole new solution in Visual Studio, so I would like to add a way to also generate a product's documentation during that process.
My question regards merging H&M projects, which are common to all products, to this new project. The Help & Manual XML Language Reference states that a navref node contains an id attribute and this id must be unique. By checking on other H&M projects we have, I noticed that this id is a very large number, probably a random-generated number. Is there a range of numbers that an id must fit in? Is it OK to generate a random number, even though smaller, to fill in? The Language Reference also states that if this id is not provided, H&M creates a new id when opening the project, but I would like to avoid that.

Thank you.
User avatar
Tim Green
Site Admin
Posts: 23157
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Generating IDs for navref elements

Unread post by Tim Green »

Hi Julio,

The navref number is taken from the creation time of the TOC or topic entry in milliseconds. I've never tried to decode it up to now but it doesn't look as though it is the standard Unix/Windows milliseconds time, as the numbers are much too high for that. I'll check... :)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Re: Generating IDs for navref elements

Unread post by Alexander Halser »

Hi Julio,

Just ignore the attribute. The NavRef IDs are random numbers - a kind of GUID - generated whenever a node does not have one. Once assigned, the node keeps this ID for its entire lifetime. That's all there is to it.

When creating a documentation programmatically outside Help+Manual, you can simply omit this attribute. It is not required unless H&M needs to synchronize two projects (language pairs) or in multi-user editing mode to synchronize multiple changes to the TOC. When the project is opened in H&M, it automatically assigns IDs to all TOC nodes that don't yet have one. When saved, the ID is permanent.

There is just one case you might want to consider: if you programmatically create a project and the project is used in multi-user edit mode. In that case, you might assign a random integer number to every node ID (e.g. time stamp + running number). The only rule is: the number must be unique within the project.
Alexander Halser
Senior Software Architect, EC Software GmbH
User avatar
julio
Posts: 118
Joined: Wed May 28, 2008 12:06 am
Location: Porto Alegre, RS - Brasil
Contact:

Re: Generating IDs for navref elements

Unread post by julio »

Thank you all for explaining how it works. Usually we do not edit projects in multi-user mode, but I will consider that.

Thanks.
Alexander Halser wrote:Hi Julio,

Just ignore the attribute. The NavRef IDs are random numbers - a kind of GUID - generated whenever a node does not have one. Once assigned, the node keeps this ID for its entire lifetime. That's all there is to it.

When creating a documentation programmatically outside Help+Manual, you can simply omit this attribute. It is not required unless H&M needs to synchronize two projects (language pairs) or in multi-user editing mode to synchronize multiple changes to the TOC. When the project is opened in H&M, it automatically assigns IDs to all TOC nodes that don't yet have one. When saved, the ID is permanent.

There is just one case you might want to consider: if you programmatically create a project and the project is used in multi-user edit mode. In that case, you might assign a random integer number to every node ID (e.g. time stamp + running number). The only rule is: the number must be unique within the project.
Post Reply