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...
Adding code to manuals and code colours
Moderators: Alexander Halser, Tim Green
- Tim Green
- Site Admin
- Posts: 23181
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Re: Adding code to manuals and code colours
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
-
- Posts: 454
- Joined: Thu Nov 16, 2006 1:29 pm
- Location: London, UK
Re: Adding code to manuals and code colours
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:"...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?
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: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.
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.Sean Godley wrote:Why is there a syntax highlighter provided if not for this purpose?
I'll be offline for the next couple of weeks so hope this helps for now...