Generating IDs for navref elements

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

Moderators: Alexander Halser, Tim Green

Generating IDs for navref elements

Unread postby julio » Mon Jun 17, 2019 12:55 pm

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
julio
 
Posts: 98
Joined: Wed May 28, 2008 12:06 am
Location: Porto Alegre, RS - Brasil

Re: Generating IDs for navref elements

Unread postby Tim Green » Mon Jun 17, 2019 3:19 pm

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
Tim Green
Site Admin
 
Posts: 21098
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany

Re: Generating IDs for navref elements

Unread postby Alexander Halser » Mon Jun 17, 2019 4:08 pm

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
Alexander Halser
EC-Software Support
 
Posts: 3955
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria

Re: Generating IDs for navref elements

Unread postby julio » Mon Jun 17, 2019 5:40 pm

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.
User avatar
julio
 
Posts: 98
Joined: Wed May 28, 2008 12:06 am
Location: Porto Alegre, RS - Brasil


Return to Help & Manual 7 Forum

Who is online

Users browsing this forum: No registered users and 5 guests