Automatic links from "custom" topics

Topics: Features, General Questions
Sep 7, 2007 at 10:52 AM
Hi, I want to ask...is there any way how to automatically during the build create links from "custom topics" htm files to files that are generated from XML comments? Thanks!
Coordinator
Sep 7, 2007 at 12:20 PM
Hi,

In your custom topics just use an HTML anchor tag:

<a href="SomeNamespace_SomeType.htm">Some API topic</a>
but if you're not using the Friendly HTML file names option then you must use the GUID file name instead:

<a href="6B7D70E0-A547-4286-A055-B19BADE3EBA3.htm">Some API topic</a>
In subsequent builds, as long as the topic's name doesn't change the GUID shouldn't change either since it's not a true GUID but a hash of the topic's ID, which is auto-generated by Sandcastle from the topic's name.

In a future release of DocProject you may be able to use <see cref="T:SomeNamespace.SomeType">Some API topic</see> instead.

Does that answer your question?
- Dave
Sep 13, 2007 at 3:53 PM
Hi Dave,
first thanks for your reply :)

In fact, the question is, whether DocProject or SandCastle can insert these hyperlink tags automatically, when name of the class, interface or any other object appears in custom topics. I've heard that some tools can do this, however I haven't seen it yet working.

Thanks,
Hana
Coordinator
Sep 13, 2007 at 5:19 PM
Hi Hana,

So you mean that if I were to have documentation like this:


<summary>Create a Person instance and call the Greet method.</summary>

you would expect Sandcastle to produce:


Create a <a href="Namespace_Person.htm">Person</a> instance and call the <a href="Namespace_Person_Greet.htm">Greet</a> method.

automatically, without any other information?

That's an interesting request, but I have some questions about how you'd expect it to work:

  1. What happens if there are multiple Person classes in different namespaces?
  2. How would I simply use the word Greet without it being made into a hyperlink, if I wasn't referring to the Greet method in particular?
It seems to me that this feature might be more trouble than it's worth...

I already mentioned that in a subsequent release of DocProject you'll be able to use <see> style tags in custom topics, which should make the process easier since you won't need to know the final HTML topic file's name when authoring content. I'm also going to add another feature that will allow you to simply drag/drop topic nodes from a tree into custom content and a <see> link will be generated automatically.

If these new features will not be suitable for your scenario then please let me know if you have any ideas for improvement.

Thanks for the feedback,
Dave
Sep 17, 2007 at 4:30 PM
In the modern era of automated documention, I think this is a basic requirement. It's also not such a tall order, technically. Take freeware doxygen for C/C++ as an example.

Doxygen creates links from the custom topics into the reference in every case, unless you explicitly tell it not to.

There are solutions to the 2 problems you raise:

- What happens if there are multiple Person classes in different namespaces?
By creating a more unique reference. In C++, that is ClassName::MethodName().

- How would I simply use the word Greet without it being made into a hyperlink, if I wasn't referring to the Greet method in particular?
Doxygen recognizes the percentage symbol as an instruction to ignore a specific trip. So %Greet tells doxygen not to create a link there; for Greet, a link is creted to the Greet class.

Why should a technical writer have to work so hard to put in all these links manually?
Coordinator
Sep 17, 2007 at 5:09 PM
Hi,


In the modern era of automated documention, I think this is a basic requirement. It's also not such a tall order, technically. Take freeware doxygen for C/C++ as an example.

Doxygen creates links from the custom topics into the reference in every case, unless you explicitly tell it not to.

I can't comment on other software that generates automated documentation since I don't use any, but I will say that I agree that it wouldn't be too difficult to implement although it's something that should be implemented by Sandcastle or a custom build component, but not DocProject. That way your documentation can be used with any tool in the future, not just DocProject :)

I recommend that you request this feature in the forums for Sandcastle:

http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1

Anyway, I was simply questioning its worth and whether I myself, as a documentation author, would like to use a feature like this.


There are solutions to the 2 problems you raise:

- What happens if there are multiple Person classes in different namespaces?
By creating a more unique reference. In C++, that is ClassName::MethodName().

So I'd have to write the following in my previous example?

<summary>Create a TheNamespace::Person instance and call the Greet method.</summary>

I'd much rather use a <see> link then because it's explict so there's no ambiguity and XML markup is more widely recognized, flexible, and also something that you'd be using already in your xml code comments.


- How would I simply use the word Greet without it being made into a hyperlink, if I wasn't referring to the Greet method in particular?
Doxygen recognizes the percentage symbol as an instruction to ignore a specific trip. So %Greet tells doxygen not to create a link there; for Greet, a link is creted to the Greet class.

You see, I think I'd rather have a feature like the following instead: When I don't want "greet" to be a link I don't do anything special, since raw text is always treated as raw text. Then, if I do want "greet" to be a link I simply type some key combination like Ctrl+L before I enter the text, greet, and DocProject will change it to a <see> link automatically after Enter is pressed on the keyboard. Alternatively, I could add a button that, when pressed, would change the selected text into a <see> link automatically, prompting the user if the text is ambiguous as the name of an API element.


Why should a technical writer have to work so hard to put in all these links manually?

He/she shouldn't, which is why I plan to implement that drag/drop feature that I mentioned previously. I understand if you don't want to use the designer and that's why I intend to make drag/drop work even in source mode.

But the new feature that I just mentioned above would make authoring links even easier. Please let me know what you think.

Thanks for the feedback,
Dave