4

I am currently using AsciiDoc for documenting my software projects because it supports PDF and HTML help generation. I am currently running it through Cygwin so that the a2x toolchain functions properly. This works well for me but is a pain to setup on other Windows computers. I have been looking for alternative methods and recently revisited Sphinx. Noticing that it now produces HTML help files I gave it a try and it seems to work well in the small tests I performed.

My question is, is there a way to specify map id's for context sensitive help in the text so that my Windows programs can call the proper help API and the file is launched and opened to the desired location?

In AsciiDoc I am using pass::[<?dbhh topicname="_about" topicid="801"?>]. By using these constructs a context.h and alias.h are generated along with the other HTML help files (context sensitive help information).

gilbertbw
  • 634
  • 2
  • 9
  • 27
Bluebill
  • 147
  • 2
  • 11

1 Answers1

2

I do not know about AcsiiDoc much, but in Sphinx you can reference arbitrary locations by placing anchors where you need them. See :ref: role.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
anatoly techtonik
  • 19,847
  • 9
  • 124
  • 140
  • I tried adding the anchor and generating the htmlhelp but the context.h and alias.h files were not created. The link would need to have number which is used by the htmlhelp as a mapid. – Bluebill Apr 27 '10 at 12:24
  • The MSDN page at http://msdn.microsoft.com/en-us/library/aa164218%28office.10%29.aspx specifies that you may display required page by either using the HH_HELP_CONTEXT command (your map ids) or HH_DISPLAY_TOPIC. The latter case requires that you know the name of HTML file inside of CHM, but for Sphinx this is easily calculated. For example, the source file markup/inline.rst will produce markup/inline.html path in CHM. If you need to generate additional html anchors for section headings - they are turned off for HtmlHelp, but could be added on request. – anatoly techtonik Apr 28 '10 at 20:24
  • techtonik, where would I go to request that the anchors for section headings be turned on for HtmlHelp? – Bluebill May 11 '10 at 14:38
  • You need to subscribe to this bugreports on BitBucket http://www.bitbucket.org/birkenfeld/sphinx/issue/400/paragraph-anchors-in-htmlhelp – anatoly techtonik May 12 '10 at 06:43
  • 1
    https://github.com/sphinx-doc/sphinx/issues/584 seems to be the relevant link now. – legalize Jun 29 '15 at 00:45