Pelles C forum
Pelles C forum => General discussion => Topic started by: CandCPlusPlus on August 26, 2022, 08:24:15 PM
-
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
-
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.
-
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
-
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
- name: "Animate_Close"
href: /windows/desktop/api/Commctrl/nf-commctrl-animate_close
-
Yes the Git repository is far from complete.
I converted those from
- name: "Animate_Close"
href: /windows/desktop/api/Commctrl/nf-commctrl-animate_closeinto
<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
-
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
-
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
-
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.
-
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.
-
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.
-
Best working offline documentation was MSDN 2012 ?
After that, MS didn't care about Win32 documentation and ruined it.
-
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.
-
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.
-
The DirectX folders are:
Direct2D
DirectShow
DirectWrite
direct3d10
direct3d11
direct3d12
direct3d9
direct3darticles
direct3ddds
direct3ddxgi
direct3dgetstarted
direct3dhlsl
direct3dtools
directcomp
directdraw
dxcore
dxmath
-
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
-
Basically, Microsoft has open sourced the win32 documentation but it's somewhat of a mess. A big project to fix it.
In doing some experimentation over the years, I discovered that in several spots the Win32 documentation is flat out wrong or out of date. For example, Rich Edit 3.0 (riched20.dll) and Rich Edit 4.1 and newer (msftedit.dll) support at least several features for a long time that the documentation says it does not support (especially related to tabstops). One could even somehow put notes in the documentation about stuff like this.
I also discovered a bug in Rich Edit 3.0 that has never been fixed. If you enable justified text, numbered bullets will eventually display improperly, distorted or not at all in Rich Edit 3.0 (riched20.dll). The bug doesn't exist in Rich Edit 4.1 and newer. Long standing unfixed bugs. lol O.O
-
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.
That reminds me, I didn't even mention the last step I took. I used notepad++ to replace all instances of ".md" in all of the files with ".html" to fix broken links.
-
This talk about help systems should be Pelles C unrelated, as poide.exe have Add-In interface for it.
some examples for searching help with keyword using different shelp sources.
https://forum.pellesc.de/index.php?topic=7250.msg27566#msg27566
https://forum.pellesc.de/index.php?topic=5162.msg19862#msg19862
https://forum.pellesc.de/index.php?topic=5320.msg20437#msg20437
https://forum.pellesc.de/index.php?topic=4442.msg16521#msg16521
There might be more of them.
-
Point taken, thanks. It did get off track and into the weeds of help files.
I'll post my updated Pelles C developed toc.yml converter to .hhc and .hhk for others.
Further discussion can be handled by e-mail or other means.
John Z
P.S. I will finish Controls.chm eventually and post probably in SourceForge.
-
A new topic for Win32 help systems is good idea, like under Pelles C - General discussion.
-
A new topic for Win32 help systems is good idea, like under Pelles C - General discussion.
I already have somewhat of a discussion related to help content in my main suggestion thread and I created this thread because of that. It would be good to just move this whole entire "Help viewer and help content" thread to Pelles C general discussion. Maybe leave discussion of the help system that's more related to Pelles C in my main suggestions thread? Would one of the mods please move this "Help viewer and help content" thread. I renamed it too. :)
-
Point taken, thanks. It did get off track and into the weeds of help files.
I'll post my updated Pelles C developed toc.yml converter to .hhc and .hhk for others.
Further discussion can be handled by e-mail or other means.
John Z
P.S. I will finish Controls.chm eventually and post probably in SourceForge.
I'm almost thinking one could create a github or sourceforge site for all of this. Convert all (or just the folders I suggested) of the documents to html, fix the table of contents and people could, steadily over time, fix all of the broken links. Leave the source as html so that it can bit steadily fixed by everyone including the original poster. HTML is a little more flexible than markdown as lots of old and new software supports it and there are even some WYSIWYG HTML editors out there.
-
I'm coming around to the conclusion that this is a bit premature. The GitHub .md files are so incomplete, just the Controls section has more than 5000 links back to Micro$oft web sites. Probably half to 2/3 might be duplicates of course for example NMHDR must have 15 same links itself - every time mentioned somewhere.
Anyway I'm still putting in the man hours 'fixing' Controls after that we'll see.
Of course this depends on the desired end result. Maybe the links are not that important. In that case I think the methodology
to convert from .md to .html to .mhsc is fairly well defined and tested and straight forward. TimoVJL's viewer system then would be 'good to go', it does not I believe, acknowledge/display links anyway.
John Z
-
There is also other viewer version for .mshc :
https://forum.pellesc.de/index.php?topic=7259.msg27602#msg27602
-
Even with broken links the documentation could still be useful. However, it would be better to have working links.
I wonder if one could create a tool to automate the process of replacing the links. Actually, you could somehow create a GUI tool that lists all of the links in the documentation, find out (possibly manually) what each link goes to on Microsoft's web site, replace all instances of that link with the actual article in the offline documentation and check it off of a "to do" list.
I imagine you could even automate the process slightly more by having the tool find the documentation on the Microsoft web site and searching for similar or identical articles in the offline documentation.
Building and fixing all of the offline documentation is a worthwhile project, IMO, because Microsoft rarely, if ever, changes the Windows (Win32) API nowadays. The newest and only additions I can think of are for touch screens, high DPI and high DPI screen/monitor related. Your Controls CHM will be useful and accurate for quite a long time and the same will be true of the CHM files for any of the other folders in the documentation. All the breaking changes happen in .NET Core nowadays.
-
Actually, you could somehow create a GUI tool that lists all of the links in the documentation, find out (possibly manually) what each link goes to on Microsoft's web site, replace all instances of that link with the actual article in the offline documentation and check it off of a "to do" list.
The issue, at least for me, is the https links are for documentation that has not been ported into the GitHub repository. If it has not been ported into the repository there is no assurance that it is covered by the MIT license. So if one were to just grab it off the Microsoft web site and use/publish it elsewhere that could be a big liability.
I imagine you could even automate the process slightly more by having the tool find the documentation on the Microsoft web site and searching for similar or identical articles in the offline documentation.
:) Sounds like a good 'first' C project for you. :)
Building and fixing all of the offline documentation is a worthwhile project, IMO, because Microsoft rarely, if ever, changes the Windows (Win32) API nowadays.
Probably this weekend Controls.chm and Controls.cab will be available on SourceForge. I've completed the conversions. I just need to start a new project on SourceForge. I don't have a GitHUb account. The files are too large to post in this forum.
I'll update here when it is ready.
John Z
Update: Go here -> https://sourceforge.net/projects/windows-controls-api-docs/
-
The issue, at least for me, is the https links are for documentation that has not been ported into the GitHub repository. If it has not been ported into the repository there is no assurance that it is covered by the MIT license. So if one were to just grab it off the Microsoft web site and use/publish it elsewhere that could be a big liability.
True. I wouldn't recommend pulling content directly from Microsoft's docs.microsoft.com web site as the MIT license may not apply there. I was suggesting comparing the content in the links with the content at https://github.com/MicrosoftDocs/win32 and https://github.com/MicrosoftDocs/sdk-api .
I did noticed too that https://github.com/MicrosoftDocs/sdk-api has some content that is missing from https://github.com/MicrosoftDocs/win32 .
-
Now available:
Download offline Controls help file at:
https://sourceforge.net/projects/windows-controls-api-docs/
Default download is Controls.chm but under 'files' Controls.cab can be downloaded as well.
John Z
Well not a lot of downloads for the new .chm or mshc file. 15 for .chm and 0 (Zero) for the .cab (mshc version).
It does take a while to build up steam but first 10 days are not showing high demand.....
-
I was thinking of adding the GDI and GDI+ documentation, however it is not worth the time and effort, at least for now. Checking the links in these topics shows about 70-75% of the references are just links back to Micro$oft web sites. This is not good for off-line documentation.
The Controls.chm has been downloaded only about 18 times in a month, and Controls.cab maybe once.
So I'm not going to pursue this anymore.
John Z
-
I like and use Chm files but they are certainly not the only option.
At the risk of overstating the obvious, Microsoft has had a DOWNLOAD PDF option
on their MS App Development Pages for quite some time. The pdf's that it creates
are hyperlinked, searchable, and contain any images that are a part of the topic
that one is looking at.
Typically the DOWNLOAD PDF shows on whatever page you're browsing.
For example GDI+ --- See attached screen shot.
DOWNLOAD PDF generates a file named "document.pdf", so it is up to
you to rename the files as you download them.
Below is the list of pdf's that I downloaded in late 2021 / early 2022.
There is much more that can be downloaded but these are what I started with.
12/29/2021 09:11 PM 4,443,316 Automation.pdf
12/29/2021 08:57 PM 13,709,892 Component Object Model (COM).pdf
12/29/2021 08:56 PM 163,840 Compression API.pdf
12/29/2021 09:02 PM 2,310,297 Data Exchange.pdf
12/29/2021 08:47 PM 2,613,216 Developing Desktop Win32 apps.pdf
12/29/2021 09:12 PM 2,486,178 Dialog Boxes.pdf
12/29/2021 08:44 PM 10,854,150 Direct2D.pdf
12/29/2021 08:45 PM 7,546,970 Direct3D 12 Graphics.pdf
12/29/2021 08:41 PM 12,246,477 GDI+.pdf
12/29/2021 09:14 PM 963,048 High DPI.pdf
12/29/2021 08:36 PM 7,638,660 Internationalization for Windows Applications.pdf
12/29/2021 08:21 PM 5,465,497 Menus and Other Resources.pdf
01/23/2022 06:10 PM 12,976,800 Microsoft CRT Reference(2022).pdf
12/29/2021 08:54 PM 3,714,989 Network Management.pdf
12/29/2021 08:34 PM 29,558,942 The Windows Shell.pdf
12/29/2021 08:35 PM 9,979,310 Windows Accessibility Features.pdf
12/29/2021 08:20 PM 4,970,943 Windows and Messages.pdf
12/29/2021 09:05 PM 16,559,253 Windows Controls.pdf
12/29/2021 08:40 PM 7,916,056 Windows GDI.pdf
12/29/2021 08:50 PM 80,934 Windows HTTP Services (WinHTTP).pdf
12/29/2021 08:51 PM 3,258,426 Windows Internet.pdf
12/29/2021 09:18 PM 7,308,203 Windows Multimedia.pdf
12/29/2021 09:16 PM 5,957,451 Windows Runtime C++ reference.pdf
03/13/2022 08:13 AM 14,862,043 Windows Shell.pdf
12/29/2021 08:53 PM 11,162,005 Windows Sockets 2.pdf
12/29/2021 08:18 PM 146,367 Windowsx.h.pdf
-
It is a good point, and I have downloaded the pdf files for Common Controls and others. The PDF is a good format, well supported, but like the other methods it is not truly an off-line resource. There are many links in the PDF(s) that point back to the Micro$oft web site to get more information. Example: if one clicks 'CreateWindowA macro' link in the PDF the link opens the Micro$oft web https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-createwindowa rather than include that information in the PDF. I suspect there are as many links in the MS PDF docs as I found were needed in the Controls.chm I created from the GitHub release.
So the idea/hope with the GitHub documentation release was that a truly complete off-line document could be produced. Alas not going to be, at least with the current released docs.
John Z