Adding code to manuals and code colours

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

Moderators: Alexander Halser, Tim Green

Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Adding code to manuals and code colours

Unread post by Sean Godley »

Hi all,

I am currently writing a manual that will include a lot of samples of coding. I am taking the information from an older manual and I am wondering if there is any kind of default setting in order to transfer code and retain the existing colour/structure. Are there any in-built options to assist in including code? If anyone has any relevant/associated information, that would be great.

TIA,

Sean
User avatar
Tim Green
Site Admin
Posts: 23153
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,

You can't import the code syntax highlighting from your programming editor because that is applied dynamically there. However, Help+Manual does have its own syntax highlighter. See here in the documentation for details:

http://www.helpandmanual.com/help/index ... syntax.htm
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.
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Great, thank you again Tim.

Sean
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Hi Tim, and thank you again for your help. However, I am still having an issue after following your instructions. When I copy and paste the code into my browser and then select it to do the syntax highlighting, there seems to be some kind of issue in that the code is not changing to the correct colours, or that it simply all goes to the same colour. Is there a way to fix this? When I try with other code it works okay, but with the code I am using it is problematic. Here is a sample of the code:

HRESULT PXCV_CheckPassword(
PXVDocument Doc,
BYTE* pPassword,
DWORD PassLen
);

Thank you,

Sean
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

P.S. I feel I should clarify - in order to create clean content, I am copying code from the live site that I'm making the manual from into Notepad in order to make it rich text and avoid additional data in the XML section of the manual. Is it possible that this is the issue?

Thanks again,

Sean
User avatar
Tim Green
Site Admin
Posts: 23153
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,

What do you mean when you refer to copying and pasting the code into your browser? The syntax highlighter in Help+Manual only works within the Help+Manual topic editor itself. The source is XML, not HTML, so you can't copy that to a browser directly. You could only do that with the HTML, for example from WebHelp output...
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.
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Hi Tim,

What I mean is that I am following the instructions as detailed in the link that you sent, I.e.:

1.Paste your program code into your topic and select it.

2.Select the btn_syntax Syntax Highlighter tool in Write > Font (click on the arrow to the right of the icon to display the menu) then select the language parser you want to use from the list displayed.

When I do this the text style of the code changes but the syntax highlighter does not work, even when I go to 'Customize...' and change the colours around for the various code components. Here are some further examples of the code I am trying to highlight:

HRESULT PXCV_DrawPageToDC(
PXVDocument Doc,
DWORD page_num,
HDC hDC,
LPPXV_CommonRenderParameters pParams
);

HRESULT PXCV_DrawPageToDIBSection(
PXVDocument Doc,
DWORD page_num,
LPPXV_CommonRederParameters pParams,
HDC hBaseDC,
COLORREF backcolor,
HBITMAP* pResDIBSection,
HANDLE hSection,
DWORD dwOffset
);

HRESULT PXCV_DrawPageToIStream(
PXVDocument Doc,
DWORD page_num,
LPPXV_CommonRenderParameters pParams,
COLORREF backcolor,
LPPXV_DrawToImageParams pImageParams,
IStream* pDest
);

Many thanks,

Sean
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:with the code I am using it is problematic. Here is a sample:
HRESULT PXCV_CheckPassword( PXVDocument Doc, BYTE* pPassword, DWORD PassLen );
That's a function declaration (for something like the PDF-XChange Viewer SDK). I've tried pasting this into a C/C++ header in various IDEs and the only thing that gets highlighted is the function name, like this:
vs-code-test-dot-h.png
What highlighting are you trying to reproduce? Which tool currently does it the way you want?
You do not have the required permissions to view the files attached to this post.
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Hi Simon and thank you for the feedback and input. Yes, I am currently writing the manual for the PDF X-Change Editor SDK. I would like the code to appear in the manual as it does on the existing help page, which is located here:

http://help.tracker-software.com/DEV/de ... ckpassword

Our developers have told me that it should possible for syntax highlighters to achieve this, but as of yet I am unable to reproduce it. Any input you have is hugely appreciated.

Many thanks,

Sean
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:I would like the code to appear in the manual as it does on the existing help pages [e.g.]http://help.tracker-software.com/DEV/de ... ckpassword
Hi Sean

I took a look at http://help.tracker-software.com/DEV/de ... ckpassword.

The syntax highlighting is provided by scripts from http://alexgorbatchev.com/SyntaxHighlighter/. These will only work on web pages, but if you don't need to output in non-web formats, you could probably continue to use the SyntaxHighlighter scripts. They are imported in line 219 of your sample page, and then in line 223 we see that a special class is used to activate the highlighting feature:

Code: Select all

<pre class="brush:cpp; gutter:false" funcdecl="1">HRESULT PXCV_CheckPassword(
     PXVDocument Doc,
     BYTE* pPassword,
     DWORD PassLen
);
</pre>
Your mission is to get H&M to generate a class name that the highlighter script can recognize. You could use an H&M HTML object for this, or you could use H&M's built-in class naming convention and modify the highlighter script to accept it as a brush variable (somewhere in http://help.tracker-software.com/DEV/sy ... /shCore.js, I think).

If you are happy to have slightly less rich highlighting, you could alternatively add your reserved words to a user-defined highlighter in H&M. The steps in H&M are described in http://www.helpandmanual.com/help/hm_re ... syntax.htm. I've converted the reserved words into a list at the end of this post. In H&M select 'Custom Highlighter' and click the 'Edit Reserved Words" button. Paste this list into the window and click OK. To match http://help.tracker-software.com/DEV/sy ... eDream.css, set the appearance of reserved words to #0000ff, identifiers (all other words) to #000080 and symbols (parentheses, pointer asterixes, comma etc) to e.g. black. That should give you the result you want, except that the function name won't appear in red. I think the only way to achieve this in H&M would be to use another custom highlighter for the first line. Load the same reserved word list and set them to #0000ff as before, but set identifiers to #880000. Use this new highlighter for the first (function name) line of the declaration and the other highlighter for subsequent (parameter) lines.

Here's an example I generated using the second method with two customer highlighters:
[screenshot] Two custom highlighters used in H&M.png
If you take the first approach, could you let me know how well it works? Good luck!

Code: Select all

Here are the reserved words from http://help.tracker-software.com/DEV/syntaxhighlighter/scripts/shBrushCpp.js:
ATOM
BOOL
BOOLEAN
BYTE
CHAR
COLORREF
DWORD
DWORDLONG
DWORD_PTR
DWORD32
DWORD64
FLOAT
HACCEL
HALF_PTR
HANDLE
HBITMAP
HBRUSH
HCOLORSPACE
HCONV
HCONVLIST
HCURSOR
HDC
HDDEDATA
HDESK
HDROP
HDWP
HENHMETAFILE
HFILE
HFONT
HGDIOBJ
HGLOBAL
HHOOK
HICON
HINSTANCE
HKEY
HKL
HLOCAL
HMENU
HMETAFILE
HMODULE
HMONITOR
HPALETTE
HPEN
HRESULT
HRGN
HRSRC
HSZ
HWINSTA
HWND
INT
INT_PTR
INT32
INT64
LANGID
LCID
LCTYPE
LGRPID
LONG
LONGLONG
LONG_PTR
LONG32
LONG64
LPARAM
LPBOOL
LPBYTE
LPCOLORREF
LPCSTR
LPCTSTR
LPCVOID
LPCWSTR
LPDWORD
LPHANDLE
LPINT
LPLONG
LPSTR
LPTSTR
LPVOID
LPWORD
LPWSTR
LRESULT
PBOOL
PBOOLEAN
PBYTE
PCHAR
PCSTR
PCTSTR
PCWSTR
PDWORDLONG
PDWORD_PTR
PDWORD32
PDWORD64
PFLOAT
PHALF_PTR
PHANDLE
PHKEY
PINT
PINT_PTR
PINT32
PINT64
PLCID
PLONG
PLONGLONG
PLONG_PTR
PLONG32
PLONG64
POINTER_32
POINTER_64
PSHORT
PSIZE_T
PSSIZE_T
PSTR
PTBYTE
PTCHAR
PTSTR
PUCHAR
PUHALF_PTR
PUINT
PUINT_PTR
PUINT32
PUINT64
PULONG
PULONGLONG
PULONG_PTR
PULONG32
PULONG64
PUSHORT
PVOID
PWCHAR
PWORD
PWSTR
SC_HANDLE
SC_LOCK
SERVICE_STATUS_HANDLE
SHORT
SIZE_T
SSIZE_T
TBYTE
TCHAR
UCHAR
UHALF_PTR
UINT
UINT_PTR
UINT32
UINT64
ULONG
ULONGLONG
ULONG_PTR
ULONG32
ULONG64
USHORT
USN
VOID
WCHAR
WORD
WPARAM
WPARAM
WPARAM
char
bool
short
int
__int32
__int64
__int8
__int16
long
float
double
__wchar_t
clock_t
_complex
_dev_t
_diskfree_t
div_t
ldiv_t
_exception
_EXCEPTION_POINTERS
FILE
_finddata_t
_finddatai64_t
_wfinddata_t
_wfinddatai64_t
__finddata64_t
__wfinddata64_t
_FPIEEE_RECORD
fpos_t
_HEAPINFO
_HFILE
lconv
intptr_t
jmp_buf
mbstate_t
_off_t
_onexit_t
_PNH
ptrdiff_t
_purecall_handler
sig_atomic_t
size_t
_stat
__stat64
_stati64
terminate_function
time_t
__time64_t
_timeb
__timeb64
tm
uintptr_t
_utimbuf
va_list
wchar_t
wctrans_t
wctype_t
wint_t
signed
You do not have the required permissions to view the files attached to this post.
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Thanks a million for the help Simon, that's great. I will experiment today and let you know how I get on. You're a star!

Sean
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Hi Simon - just an update:

The solution you provided almost worked :)

The first example you gave with the list of reserved words worked okay, but the second one was a little off. I think it is an issue with the reserved words and the way that the code is written. In any case, I was able to use the first one for the main body, the second one for the titles (although 90% of the time some color editing was required, as it seemed to do the whole top line as the same color). After that I still had to go through and make some changes as, a lot of the time, the color syntax highlighter was almost correct - but some words were not 100% and needed to be corrected manually. Overall it was much faster than it would have been if I had done the whole lot manually and I'm sure a little more tweaking will get it 100% correct.

Thanks a million for your help,

Sean
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 »

Hi Sean, glad it helped.

Simon

P.S. I appreciate you were asking this as a documentation specialist, but from a software engineering perspective identifying functions and parameters by inspection in a downstream tool like Help & Manual and then applying manual code formatting is a woefully old-fashioned and fragile approach. In an earlier post you said "our developers have told me that it should possible for syntax highlighters to achieve this" but you might reasonably reply that their static code analysis tools could do a much better job creating input for documentation.

P.P.S. If all you're doing is documenting APIs (a narrow subset of technical documentation) it may be that H&M7 isn't an appropriate tool. Doing leading-edge stuff hasn't been EC Software's priority for the 14 years I've been lurking here – they excel at backwards-facing compatibility which has different benefits – so you might be better 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. Sorry Alex and Tim but you know what I mean...
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Hi Simon - thanks for the input.

Yes, you are correct - I am a technical writer and not a programmer and I agree that the process used definitely feels old-fashioned, inefficient and error-prone. However, I am simply following the instructions as detailed in the Help and Manual help pages. Why is there a syntax highlighter provided if not for this purpose?

The reason I mentioned that our developers said it should be possible is because it has been done before in our help pages that are currently on the live site, for example here:

http://help.tracker-software.com/DEV/de ... lex_object

However the process used in that case was for webpages only (would not work with PDF versions, which we need) and also included Javascript which, I believe, made it incompatible with Help and Manual. I asked our developers for assistance before coming to this forum. They had a look at the Help and Manual syntax highlighter and concluded that it was not directly compatible with our code (despite its being compatible with other highlighters) but that there might be a way to make it possible, which is why I posted here. I do not know which tools they use for static code analysis but I will ask them today - thank you for the idea.

I am doing a lot more than documenting APIs - the two most recent manuals have a focus on APIs but the six before that were very much suited to the Help and Manual format. Could you please clarify what:

"...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?

Thank you again,

Sean
Sean Godley
Posts: 92
Joined: Sun Apr 24, 2016 6:10 am

Re: Adding code to manuals and code colours

Unread post by Sean Godley »

Hi Simon - just an update:

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.

Cheers,

Sean
Post Reply