Edit Caption Greyed Out?

[Dale Aceron]

When I try to edit the caption on an XML file, it's greyed out.
Why would that be?

2020-01-08_16-04-16 edit caption-min.jpg

[Tim Green]

Hi Dale,

When I try to edit the caption on an XML file, it's greyed out.

That's because the XML files don't have captions. The XML files section just lists all the topics in your project, whether or not they are included in the TOC. The TOC is really just a list of hyperlinks with captions, and multiple TOC entries can point to the same topic file. So you can only edit the TOC caption when it's selected in the TOC: The TOC entry refers to a topic file, but the topic file doesn't refer to the TOC entry.

[Dale Aceron]

Oh boy. So I think we've been doing something incorrect.
We would create a Topic, then delete it but keep it's referrer.
When we embed a Snippet into a Topic, we refer to the XML file since there is no Topic anymore.
But now, I cannot change the caption which puts me in a bit of a bind.

What are your thoughts on our workflow?

[Tim Green]

Hi Dale,

If you're deleting in the TOC and keeping the referred topic file then that is exactly what you need to do for snippets. Again, however, it's important to understand that you are not deleting a "topic". The TOC is only a list of links, that is ALL it is. When you delete something in the TOC you are just deleting a link in a list, nothing more. The topic file is always in the Topic Files section, whether it's in the TOC or not. If you create a topic directly in the Topic Files section no TOC entry gets created -- that's the quickest way to create a snippet.

If you need to put it back in the TOC it's easy to do: Just drag the topic file into the TOC and a TOC entry will be created automatically. You can also do it with the New Topic tool: In the dialog, select the "TOC Link" option on the left instead of the "New Topic" option. Then select "Link to topic in this project" on the right and the ID of the topic file you want to include in the TOC and a TOC entry will be created to that file.

However, if you are just using the files as snippets they don't need captions, because captions are TOC entries. Similarly, even if they have headers, the header is not used when they are used as snippets. It is just ignored.

Important: Excluding snippets with build options

If you are only using topic files as snippets you don't want them to be exported as HTML files when you generate WebHelp, CHM, or eWriter, because then they would show up in the search results, which can confuse users. So you should set the build options of your snippet topics to "None".