CSH question on header files

[AlanKearns]

I'm looking at the possibility of creating CSH with madbuild, instead of the Flare UI, which would mean maintaining various project files directly as text files. My questions are:

1. If I've sent my header file to my developer, does a copy also need to remain in my project at point of build, or is it enough for the Alias file to be there?

2. If the project *can* build without containing the header file, would this restrict the developer to calling topics via the Identifier text name, or would they also still be able to use the numerical ID?

3. If the project *can't* build without containing the header file, does it make any difference if the developer's copy is using one of the formats/syntaxes that's different from the Flare default '.h' one that's in the project?

These questions assume that the Alias and Header have the same correct set of identifier names. That is, no mismatches.

[NorthEast]

In Flare, CSH links set up in the alias editor use both the header file (.h) and the alias file (.flali).

* The header file is a text file that contains a list of all the identifiers (a text string ID) and values (a numeric ID). Only one of these is used in a CSH call. If you're producing HTML5 output, you can use either the identifier or value in the CSH call, but using the identifier (text string) usually makes more sense as it's more readable. So if you use identifiers, then you just need to make sure the identifiers in your header are unique, and the values can be anything you want (as they'll not be used).

* The alias file is an XML file that contains list of only those identifiers (or values) that you've linked topics, and the topics they're linked to. It doesn't contain any unlinked identifiers.

So:
1. I'd recommend that you leave the header file in the project, as it makes little sense to remove it. Whilst you don't technically need the header file to build the target, you do need the header file to use the alias editor properly and link identifiers to topics.

2. I don't think it would restrict using the identifier text string or the value.

3. The purpose of the header file for a developer is information only. The only thing that matters is that the developer uses the correct identifier (or value) when they make the CSH call. You do need to decide who is responsible for creating/maintaining the header file, so either you provide it to your developer or vice versa. The header file format used by Flare is standard, and you need to use that if you want the header file to work in Flare's alias editor.

[AlanKearns]

Thanks for that.

On 1, as I won't be using the Alias editor (because I won't be using the Flare UI), I'll think about leaving it out. Actually, there isn't really a true project to leave it out of - the build is being done by madbuild as part of a pipeline which creates/imports the various Flare files on the fly from template XML and source content Markdown.

On 2, I'm not sure how it would work. If the developer chooses to use the value method of identifying, AND there's no header file in my project, and alias files only contains the text identifier, how would their CSH call find the topic to display, as the values wouldn't exist on my side? I noticed that deleting the header file and doing a build threw 'Topic not declared in any header file' error, which I think is a hint that the number method won't work in this situation, even if the text identifier would.

It's looking to me like I can do without the header so long as the developer uses the text identifiers in calls, and they stick to the ones I put in the Alias file I create in Notepad++.

[NorthEast]

Thanks for that.

On 1, as I won't be using the Alias editor (because I won't be using the Flare UI), I'll think about leaving it out. Actually, there isn't really a true project to leave it out of - the build is being done by madbuild as part of a pipeline which creates/imports the various Flare files on the fly from template XML and source content Markdown.

On 2, I'm not sure how it would work. If the developer chooses to use the value method of identifying, AND there's no header file in my project, and alias files only contains the text identifier, how would their CSH call find the topic to display, as the values wouldn't exist on my side? I noticed that deleting the header file and doing a build threw 'Topic not declared in any header file' error, which I think is a hint that the number method won't work in this situation, even if the text identifier would.

It's looking to me like I can do without the header so long as the developer uses the text identifiers in calls, and they stick to the ones I put in the Alias file I create in Notepad++.

For (1), if you're creating the alias XML file (*.flali) outside of Flare, then you just need to copy that file into the Flare project that you're building. Obviously, the targets also need to be set to use that alias filename. The alias file itself only contains the identifier text string and topic link.

For (2), the alias editor will give warnings, but the build process will complete fine with just the alias file and without the header.

As the alias file only includes the identifier text and not the value (which is in the header file), then the value isn't going to be included in the output, so the developer can only use the identifier text (not value) in a CSH call.
So your project alias file (*flali) would have:
<Map Name="IDENTIFIER" Link="/Content/Topic.htm" />
In the output Alias.xml file, this would be generated with a value for (resolvedId):
<Map Name="IDENTIFIER" Link="Topic.htm" ResolvedId="-2147483648" />

So if you want to use the value in CSH calls, then you need to include the header file for the build process, and the ResolvedId value in the output will be populated. But whether you use identifier or value is entirely is up to you, and there's no real need to use the value if you don't want to.

[AlanKearns]

That's how it is. It all comes down to what Flare puts in the file data\Alias.xml in the output. It always includes a NAME value for the text identifiers, so they always work, but if the header file isn't present for build, the ResolvedId value is a big negative number (so references to values don't work), instead of the correct ID value in the header.

[Edit] We overlapped!

[NorthEast]

Yep, but it doesn't matter about that value/ResolvedID, because it serves no purpose if you're going to use the identifier text in the CSH call.