In Functions reference pages, Is it possible to add links to UDFs in other groups?

[c.haslam]

I am looking at Help > UDFs > Process Management. I suggest that it would be helpful to have links on this page to _WinAPI_OpenProcess, _WinAPI_GetExitCodeProcess, and _WinAPI_CloseHandle, and possibly other Process-related UDFs.

Is this possible?

Edited June 7, 2015 by c.haslam

[water]

In the help file for every function there is a "Related" section pointing to some other related functions.
Most of the time this is to functions in the same UDF, but I can imagine that your suggestion might be useful.
Let's see what the Devs say.

[jpm]

In the old time relation with Builtin and UDF was impossible but now "Related" section can incorporated any "Functions"

[c.haslam]

Can Related contain links to Reference pages?

For example, can Function Reference > Process Management > ProcessList() > Related contain a link to User Defined Functions Reference > WinAPIEx > Process and Synchronization > Process Management > Process user defined functions Reference ?

This would avoid having a long list of links in Related.

Edited June 8, 2015 by c.haslam

[jpm]

not really, some internal specificic name with ... for GUI as I remember

[guinness]

That would require a rewrite and I am not about to do that anytime soon, given the fact last summer I did a re-write of the help file build scripts.

[c.haslam]

Guiness, I understand (and accept) your reluctance to rewriting again. In a Tracticket (which now seems to have disappeared), I got an answer that said that the txt to htm converter probably leaves <a href="..."....</a> in Related in a .txt file unchanged. Is this true?

My draft AutoRelate script suggests, for example: In each of the pages for which links exist in built-in Process Management.htm, except for links to Dll*():

• Add a link to UDF > Process Management
• Add links to _WinAPI_CreateProcess.htm, _WinAPI_GetCurrentProcess.htm , etc.

 

 

Edited June 15, 2015 by c.haslam

[guinness]

The text to HTML parser doesn't touch embedded HTML, though in all honesty it should have never come to this, as now it's a maintenance nightmare. It would have been far better to have some template set out e.g. [a=http://somesite]Text[/a] that would then be parsed to an a element for example. But again, it all takes time and sufficient planning. Something I and the other devs (I guess) don't have.

[c.haslam]

At least the <a hrefs...</a> will be generated by one line in my script, so it should be "check one function then the others are the same format". If you catch one error, you will have caught them all (or almost). If I get one wrong, you will be able to rap me on the knuckles!

[guinness]

What script do you have?

[c.haslam]

guinness, I have been writing (and am writing) my own script. It is experimental. Before I go on to actually adding links to .txt files, I am trying to make sure that all links would be (will be) what should be. I started by looking for the xxx in built-in the names of xxx Management.htm files in the names of UDF Management.htm files. Then, where appropriate, I fished out the function names in native Management.htm files, and looked for them in the names of UDF Management.htm files. Then I looked in individual UDF function names. For the functions in WinAPI Management.htm, I found I had to look in the descriptions of the functions. This evening I have been looking for false positives, and I think/hope I have eliminated all of them.

The script puts the results into an array, and I print this out as a multi-column report. The headings are 'Add link in','Include','Exclude','Link to','Match method'. I intend to add links to function .txt files, in some cases to all .txt files in a management group. Include, so far, is only used for restricting the .txt files for the FileDirDisk group: all the links in this group that I have identified pertain only to File* functions. There is one case where Exclude seems to apply: there should be no links from Dll* files to UDFs. For the destinations of links, I propose to point to management groups where possible, and where not possible, to function .txt files.

All the effort so far has been towards adding <a href's to help pages for built-in functions, pointing to UDFs. I am avoiding adding Relateds that are already there.

Early versions of the report are on Trac. There are bugs in them, but they do give an idea. Perhaps tomorrow I will upload a version for which I will seek approval of you devs.

Hopefully, my effort will help others (and me!) find functions they and I need more easily. There truly are many UDFs!

[guinness]

I doubt it will be easy to patch your code with the build scripts. But thanks for taking the time.

[c.haslam]

So will my efforts be useful?

I am trying to be as systematic as possible but this is not easy, given the organization of the Help.

I do hope to hand over to you a script which will be useful in the future. So far, I have avoided doing anything semi-manually: it is all rule-based.

[guinness]

Could you at least show me something? Are you following the guidelines for when developing a UDF/build script? Have you integrated into the latest build script? Have you tested by building the help file yourself? Are you sure that feature will add value to the help file?

Edited June 17, 2015 by guinness

[guinness]

By the way, I developed the build scripts using an OOP-like pattern. Therefore this is why it might be confusing.

[c.haslam]

I have reached the point of identifying what-I-think-are-reasonable links from native functions to UDFs for all except about 620 UDFs, which I haven't thought about yet. I have rejected some functions as un-linkable, because there are no native functions like them. Almost all of the 620 are _WinAPIs. The current list of un-linkables is

['$tag','_Array','_Crypt','_Debug','_EventLog','_Excel','_FTP','_GDIPlus','_GetIP','_GUICtrlHeader', _
    '_GUICtrlIpAddress','_GUICtrlRebar','_GUICtrlStatusBar','_GUICtrlToolbar','_GUIImageList','_GUIScrollBars', _
    '_GUIToolTip','_IE','_INet','_Mem','_NamedPipes','_Net_Share','_ScreenCapture','_Security','_SQLite','_TCPIpToName','_vi', _
    '_WinNet','_Word']

Where reasonable, the links are to Managements, not to functions.

I think that the selection data could be made into meta-data, but that is beyond my current scope.

[c.haslam]

guinness, I am thinking of proposing that WinAPI Management be split up into a number of Management groups. It would be easier for users if the 600 functions in the current group were re-grouped. Re-grouping would also reduce  the number of Related links I will propose for native functions. The help for many of the functions in WinAPI Management do not obviously tell what part of Windows they pertain to. The existing arrangement may work well for users who already know the name of a function, but if you don't know its name, can you find it? I sometimes can't.

I have found your file in which grouping and tree structure is defined. I will be recoding my script to look for, and read, files below txt2htm than below WEB_html. This will make it more consistent with your build process.

Thoughts?

[guinness]

If you could show me something that would be better. Also jpm has done a ton of work with the WinAPI, so I am not convinced whatever it is you want to do will add value.

[c.haslam]

guinness,

I have picked up possible grouping within WinAPI Management. Most of the assignments are per MSDN. In many cases, a UDF in WinAPI Management is litle more than a wrapper for a Windows function, so MSDN easily tells me how to group the UDF. Where the UDF's name is not used by Microsoft, I have looked at the UDF's code to see what Windows functions it calls. This has told me how to group the UDF.  There are cases where MSDN lists a Win API function in several groups. I picked the one that seemed logical to me.

The results of my searching are in the attached Excel spreadsheet.

Have fun!

Categories in WinAPI Management.zip

Edited June 25, 2015 by c.haslam