Adding code to manuals and code colours

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

Moderators: Alexander Halser, Tim Green

User avatar
Tim Green
Site Admin
Posts: 23154
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Adding code to manuals and code colours

Unread post by Tim Green »

Hi Sean,

The syntax highlighter in HM is quite basic, there is no denying that. If you are defining a custom highlighter you are restricted to the options provided. Also, it is not dynamic -- i.e. it doesn't work like dynamic styles. If you change the definitions in the highlighter you are using, that doesn't change the code that is already highlighted. Instead, you have to go back and re-apply to get the changes. I would agree that this is not optimal, but it is what it is at the moment... :?
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.
Simon Dismore
Posts: 454
Joined: Thu Nov 16, 2006 1:29 pm
Location: London, UK

Re: Adding code to manuals and code colours

Unread post by Simon Dismore »

Sean Godley wrote:"...starting with an automated in-house HTML5++ pipeline that generates aria-* roles and uses <dfn> and <abbr> so your core functions can be linked from things that reference them..." means?
If you were creating only web-based documentation (not PDF) and if it was mostly APIs etc., then you might be able to generate the majority of the document automatically from source code. That way you could use the modern W3C concepts directly, e.g. aria accessibility markup and the latest semantic elements like <dfn> and <abbr> which allow abbreviations or acronyms to be linked to their definitions.
Sean Godley wrote:One of our developers just informed me that the static code analysis tools they use are: Visual Studio Static Analysis Tools and, to a lesser degree, PVS Studio Analysis Tools - I hope this can shed some light on what you were saying.
Some analysis tools can emit XML files that describe functions, program structure etc. I believe VSdocman and ReSharper have some support for doing this within Visual Studio but I'm not sure how much of the information has to be manually entered as /// comments, as opposed to being inferred automatically from source. ReSharper works with Doxygen which can generate a variety of outputs, including XML which could perhaps be imported to H&M. The question is how far "upstream" the information is being captured, and how much of the "downstream" work can be automated. This would be something your developers would have strong views on: there are many factors to be traded-off. I suppose if the culture is moving towards rapid iteration and continuous integration, it makes sense to automate documentation as much as possible.
Sean Godley wrote:Why is there a syntax highlighter provided if not for this purpose?
Fair question, but not one I can answer on their behalf. H&M is IMO a reasonable middle-of-the-road tool-set, and it's got a basic syntax highlighter for source code, it's just that because you're documenting declarations you want to accentuate each function name. If the purpose of publishing to PDF is to support offline use, have you considered H&M new eBook format which is basically a website in a single file? If you didn't need to generate PDF docs I expect you could shoe-horn your current JS-based highlighter into H&M.

I'll be offline for the next couple of weeks so hope this helps for now...
Post Reply