Help viewer and help content

[CandCPlusPlus]

I decided to create a seperate thread just for help suggestions because it's getting so many replies and lots of discussion. It's great to see that I'm not the only one that still likes to have offline documentation.

A lightweight markdown and gfm (github flavored markdown) help viewer, in the style of the classic .CHM viewer or the old .hxs viewer from Visual Studio 2008, built right into Pelles C would be quite useful. Especially with the fact that Microsoft now has the full Windows API documentation right on github in gfm format under the MIT and Creative Commons licenses. Heck, I'd probably even use it for documentation unrelated to Pelles C at times.

Links:
https://github.com/MicrosoftDocs/win32
https://github.com/MicrosoftDocs/sdk-api

I should have previously mentioned that there's another really good github site from Microsoft about the Windows API. Again, all under the MIT and Creative Commons licenses.
https://github.com/MicrosoftDocs/sdk-api

[CandCPlusPlus]

One could even make it so that the help viewer can find content and find the destination of links to other content within compress files in 7z or zip format. You could than just download it straight from github and use it.

[John Z]

Having created a working Controls.chm and a working Controls.mshc from the github repository files I can tell you it is far from being completely offline.  Even after all my fixes there are still over 1000 HTTP links back to a Micro$soft web site for more information.

This is why I said it would take so long to complete....

I'm going to try to finish Controls.chm as I like to finish what I start, and then probably post it on SourceForge.  By finish I mean  fixing the 1000+ links so that they are functional.  I don't intend to pilfer from the MS web site documentation that has not been put into the Git repository .... so at least, as the Git repository stands today, the 'offline' help can't be totally offline.   I suspect the same issue will be present in the SDK-API repository.

John Z

[TimoVJL]

A quick look to toc.yml and noticed a lot of strange href:s
Perhaps not easy to create a working index database.

example in Controls

Code: [Select]

          - name: "Animate_Close"
            href: /windows/desktop/api/Commctrl/nf-commctrl-animate_close


[John Z]

Yes the Git repository is far from complete.

I converted those from

Code: [Select]

          - name: "Animate_Close"
            href: /windows/desktop/api/Commctrl/nf-commctrl-animate_closeinto

Code: [Select]

<param name="Name" value="Animate_Close">
<param name="Local" value="https://docs.microsoft.com/windows/win32/api/Commctrl/nf-commctrl-animate_close">so that the Controls.chm can reference the link correctly with MSHTML.DLL.  But of course MSHTML.dll needs updating to not report as ie11.

This problem exists in the .md base files as well.  Many, many, links back to to Micro$oft web documentation.  More than 1000 just in the Controls folder documents.  Might be too soon to count our chickens.....

In the Controls TOC:
Approximately 3300 entries in the TOC with about 1540 referencing external Micro$oft documentation web site.
About half of the documentation is still on line only....

John Z

[CandCPlusPlus]

I have noticed broken links in the documentation and the links to Microsoft's web site. It may or may be much of a problem because one could just search for whatever it is among all the documentation.

The documentation at https://github.com/MicrosoftDocs/sdk-api appears to be more complete to me. I have noticed several completely missing items with the documentation at, https://github.com/MicrosoftDocs/win32, such as the LVITEM structure. However, it does exist here, https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-src/content/commctrl/ns-commctrl-lvitemw.md

[John Z]

The documentation at https://github.com/MicrosoftDocs/sdk-api appears to be more complete to me.

Have to disagree with you my friend.  The docs at sdk-api are in worse shape to me than the /win32 docs.
A sample test at sdk-api on bcrypt directory shows 519 unresolved links and 3 resolved external links.
Only 3 files had references to other .md files yet there are 98 .md files in the category - seems off to me.
In addition there is no TOC or Index file (index.md exists with nothing useful in it). The document markdown
format used is a mishmash of markdown, html, and custom parameters, probably all geared towards a customized viewer written in json.

Also appears that all of the _ABC folders are placeholder pending completion of that topic For example
folder _activity_coordinator will probably eventually be filled with text from:
https://docs.microsoft.com/en-us/windows/win32/api/_activity_coordinator/

So not ready yet....(at least for me...)

I have noticed several completely missing items with the documentation at, https://github.com/MicrosoftDocs/win32, such as the LVITEM structure.

LVITEM is one of the many references linking back to Micro$oft web documentation, as in
<a href="https://docs.microsoft.com/windows/win32/api/commctrl/ns-commctrl-lvitema"><strong>LVITEM</strong></a>

John Z

[CandCPlusPlus]

All of the documents at sdk-api are a mishmash of html, markdown and custom parameters with yet even more broken links? What a mess. The offline documentation is in need of fixing. O.O

When there's a completely missing entry from win32 docs, you could try grabbing the one from sdk-api. You might need to fix the formatting though.

[CandCPlusPlus]

I wasn't sure where to post this so I'll post it here...

I downloaded all of the documentation from https://github.com/MicrosoftDocs/win32, converted it to all html using pandoc which took several hours and I turned it all into a single .CHM help file using FAR HTML. It was about 250MB, not anywhere as big as I thought it would be and I believe it uses compression when building .CHM files.

I used a batch (script) file to convert all of the documents en masse. I modified command line code I found on the internet.

This originally but it leads to there being no titles for each help article:
for /r "c:\NewHelp" %%i in (*.md) do pandoc -f gfm -t html "%%~fi" -o "%%~dpni.html"

I may try this to fix the titles:
for /r "c:\NewHelp" %%i in (*.md) do pandoc -f gfm -t html --shift-heading-level-by=1 "%%~fi" -o "%%~dpni.html"

Apparently you need to shift the heading levels so that certain headings become the title for the new html documents from what I've read online.

Edit: and, of course, running this after it all...
del *.md /s /q

After that, I used notepad++ to replace all instances of ".md" in all of the files with ".html" to fix broken links.

[John Z]

Well seems the right place since it is your winapi help topic of offline documentation 

First Congratulations for jumping in and trying something. I've heard of PanDoc of course but don't have it. I also have the 'Helpwaregroup' tools but have not utilized it much as I refuse to download bloat.net for something to work so that limits FARHTML.  Now unless these two tools are amazing, in which case I'm an idiot for not trying them, you have found you have a .chm documentation package using 250 Meg but with numerous unresolved issues.

You have done to the whole package what I did to just the Controls folder to test a method to get a complete working .chm help file.  BTW I only have 660 links to fix before I rebuild Controls.chm     

I would guess a number of things did not get done by those two programs.   The biggest drawback might be the lack of the contents file which lists a treeview like structure of 'Books' 'Topics' 'sub books' etc.  If FARHTML can import .hhc and .hhk files (it can see attachment, import of hhc from TOCYML) you can possible solve this deficiency by using the TOCYML tool at
https://forum.pellesc.de/index.php?topic=10571.0
to create the needed hierarchy  for the contents file.

The TOC.YML file displays the correct structure of the contents file by indenting, but this not the representation that the .hhc uses.  So TOCYML converts toc.yml to toc.hhc and toc.hhk structure. I'm fairly sure that if the toc.yml in each directory is converted, then the resulting .hhc files could all be appended together for a master .hhc which would be structured and created correctly for .chm.  Same for .hhk.  Haven't tried it but I think the worst case fix is that the header and footers need to be removed from files 'in between'.  So I would modify TOCYML to accept two more switches /noheader and /nofooter.

The next thing to check did PanDoc or FARHTML rename all of the .md references to .html in each and every newly converted .html file?  If they are still .md even if the syntax is correct for a link it is the wrong extension.

Well all for now as I seem to be writing a book ..... but there is more.

John Z

Today I will enhance ymltoc 

The error message "The upload folder is full. Please try a smaller file and/or contact an administrator." prevents the attachment of FARHTML imported hhc file 52k picture ......

Update: New ymltoc works great to create hhc files that can be concatenated to create a single hhc. Need to test hhk too.

Update2:  Works great!  Both merged HHC and HHk files open and look correct in FarHtml and MS Help workshop. 

[TimoVJL]

Best working offline documentation was MSDN 2012 ?
After that, MS didn't care about Win32 documentation and ruined it.

[John Z]

Agree, they took a wrong turn somewhere (web?).... and the old MSDN CD doesn't work right anymore either, and has it own ivt format.  I found IVT2HTML and have converted a lot of documentation and examples to HTML which I was then going to make into .chm.  I realized it was a lost cause though....

John Z

P.S.  TimoVJL as one of the top guys in the forum maybe you can get the word out to clean up duplicate attachments to free up upload space.  I went through mine and removed duplicates already, just leaving the newest version of a posting attachment.  We are out of upload space again already.

[CandCPlusPlus]

Given the state of the help content, I think the best course to take is trying to create help files out of the content that's most important and prioritizing that. There's a bunch of sections for hardware access and whatnot APIs which is not really relevant for many GUI applications. I also see a whole folder for Windows Media Player and that's not really relevant for example and there's plenty of others that don't look particularly relevant to me personally. Thinking about it, packaging each section into a separate help file and being able to download it separately, allows people to just download the parts that are relevant to them.

I personally think the most important parts are related to creating GUI apps in Windows such as common controls, messages, creating windows, text edit, richedit, GDI, controls, etc. I may post a list here at some point. There's a whole bunch of folders dedicated to DirectX which is probably a good idea to create help files for but that's a lower priority for me. Maybe even create a help file that just includes that as an option?

On a side note, maybe only include the parts dedicated to creating GUI apps with the Pelles C install? Though, size could be a problem.

[CandCPlusPlus]

The DirectX folders are:

Direct2D
DirectShow
DirectWrite
direct3d10
direct3d11
direct3d12
direct3d9
direct3darticles
direct3ddds
direct3ddxgi
direct3dgetstarted
direct3dhlsl
direct3dtools
directcomp
directdraw
dxcore
dxmath

[CandCPlusPlus]

If there's anything important that I've missed for creating Win32 GUI in general let me know. If you complete lol.

Priority help content for Win32 GUI apps from the https://github.com/MicrosoftDocs/win32 Microsoft github site:

winuser - Quite important but completely missing from: https://github.com/MicrosoftDocs/win32. It does exist when you download a zip file of the content at: https://github.com/MicrosoftDocs/sdk-api/

accessibility
activity_coordinator
apiindex
Controls
dataxchg
dlgbox
Dlls
dwm
gdi
gdiplus
hidpi
Intl
input_feedback
input_ink
input_intcontext
input_pointerdevice
input_radial
input_sourceid
input_touchhittest
input_touchinjection
inputdev
inputmsg
LearnWin32
Memory
menurc
Midl
Multimedia
OpenGL
PerfCtrs
Power
psapi
printdocs
ProcThread
SensorsAPI
shell
Shutdown
SysInfo
TSF
TaskSchd
UIAnimation
uxguide
wia
wic
Win7AppQual
win7devguide
wcs
winmsg
wintouch
WinProg
WinProg64

Priority help content for Win32 GUI apps from the https://github.com/MicrosoftDocs/sdk-api Microsoft github site:
winuser
winbase
winreg
winver
commctrl
commdlg
richedit
richole

Folders from https://github.com/MicrosoftDocs/win32 that I was unsure about how I felt:
Windows Installer. Include that, likely in a separate file? Also, quite large.
Msi

System monitor APIs, include that?
SysMon

Possibly useful, include that?
ToolHelp

Older Setup APIs, include that?
SetupApi

Security related. Include that?
SecBP

This is sketchy as far as including it with the a GUI help file. Large but slightly relevant for running GUI apps in terminal services/remote desktop.
TermServ

Networking, include that?
WNet


WinUI 3 related?
medfound

If this is only Windows XP Tablet Edition related, it's likely not relevant nowadays.
tablet