GitHub: contributing to the AutoHotkey documentation

[jeeswg]

This thread is for people to post advice/guidelines re. contributing pull requests to the AutoHotkey documentation.

[AHK v1.1/v2.0 docs]
Commits · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commits
Commits · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commits/v2
Commits · Lexikos/lexikos.github.io · GitHub
https://github.com/Lexikos/lexikos.github.io/commits

---

Style Guide

[a style guide for AHK documentation code examples by Ragnar]
v2 docs contribution questions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=49735&p=221055#p221055

---

Character Entities

Commonly used character entities in the documentation:
"&<> &quot;&amp;&lt;&gt;
←→↑↓ &larr;&rarr;&uarr;&darr;
–°© &ndash;&deg;&copy;
&nbsp;

List of XML and HTML character entity references - Wikipedia
https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

---

Example Commits For Adding New Functions

[current AHK v2 IsSet page and commit history]
AutoHotkey_L-Docs/IsSet.htm at bfcfd17673fdd1970b7b2deb453f7326b05b22b5 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/blob/bfcfd17673fdd1970b7b2deb453f7326b05b22b5/docs/commands/IsSet.htm
History for docs/commands/IsSet.htm - Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commits/bfcfd17673fdd1970b7b2deb453f7326b05b22b5/docs/commands/IsSet.htm

[current AHK v2 function index and commit history]
AutoHotkey_L-Docs/index.htm at bfcfd17673fdd1970b7b2deb453f7326b05b22b5 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/blob/bfcfd17673fdd1970b7b2deb453f7326b05b22b5/docs/commands/index.htm
History for docs/commands/index.htm - Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commits/bfcfd17673fdd1970b7b2deb453f7326b05b22b5/docs/commands/index.htm

[current AHK v2 StrCompare page and commit history]
History for docs/commands/StrCompare.htm - Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commits/bfcfd17673fdd1970b7b2deb453f7326b05b22b5/docs/commands/StrCompare.htm
AutoHotkey_L-Docs/StrCompare.htm at bfcfd17673fdd1970b7b2deb453f7326b05b22b5 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/blob/bfcfd17673fdd1970b7b2deb453f7326b05b22b5/docs/commands/StrCompare.htm

[commit to add an AHK v2 StrCompare page, and add references to various js files]
Adding StrCompare page. · Lexikos/AutoHotkey_L-Docs@2e3a072 · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commit/2e3a072b54a8da8bc5d1964461ae737f8cb85cbf#diff-950811d698cd386b1f622955fcd666be

[commit to add StrCompare to the AHK v2 Alphabetical Function Index (docs/commands/index.htm)]
Update docs · Lexikos/lexikos.github.io@c57d3b2 · GitHub
https://github.com/Lexikos/lexikos.github.io/commit/c57d3b2f6cc6a83c7cad4c63a066b571c371d66f

[in AHK v1, function names are also added here:]
Functions - Definition & Usage | AutoHotkey
https://www.autohotkey.com/docs/Functions.htm

---

Considerations / Comments By Lexikos

[is:pr commenter:Lexikos][pull requests with comments by lexikos]
Pull Requests · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/pulls?utf8=%E2%9C%93&q=is%3Apr+commenter%3ALexikos
[is:issue commenter:Lexikos][issues with comments by lexikos]
Issues · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/issues?utf8=%E2%9C%93&q=is%3Aissue+commenter%3ALexikos

[to submit a pull request to AHK v1 and v2, submit it to AHK v1 only, it will be merged with AHK v2 later]
[to submit a pull request to AHK v2 only, submit it to AHK v2]
[v2] Add AltTabMenu to the 'complete' list of AltTab Commands. Fixes #339 by SALZKARTOFFEEEL · Pull Request #341 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/pull/341
Typos by Ragnar-F · Pull Request #103 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/pull/103

[sometimes a trailing newline is needed at the end of a file]
Fix small issues by Ragnar-F · Pull Request #223 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/pull/223
unix - Why should text files end with a newline? - Stack Overflow
https://stackoverflow.com/questions/729692/why-should-text-files-end-with-a-newline/729795#729795

[keep unrelated changes as separate commits]
[keep the initial line of the commit message at or below 72 characters]
[filenames need to be specified in the correct case for links etc. to work in all cases]
[only the .htm extension is used, not .html]
Links and anchors on "styles.htm" / WinExist in Pagetitle of "IfWinExist.htm" by hoppfrosch · Pull Request #30 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/pull/30

[some complex discussions re. using git involving hoppfrosch]
Own Page for "WinTitle" - RETRY by hoppfrosch · Pull Request #32 · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/pull/32

---

Links

[info for adding new features to the source code]
GitHub: contributing to the AutoHotkey source code - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=81&t=70224

[further GitHub threads]
new forum proposal: GitHub subforum - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=3&t=69622

[guest3456]

Btw what is the bottom link of these 3?
It seems like the docs have 2 repositories for the same thing?

Commits · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commits
Commits · Lexikos/AutoHotkey_L-Docs · GitHub
https://github.com/Lexikos/AutoHotkey_L-Docs/commits/v2
Commits · Lexikos/lexikos.github.io · GitHub
https://github.com/Lexikos/lexikos.github.io/commits

there's only 1 docs repository, and that is: https://github.com/Lexikos/AutoHotkey_L-Docs/
the first two links are for two separate branches within that docs repo
the 3rd link is for lexikos' github webpage that github provides at http://lexikos.github.io/
if you look at that repo, its just an index.html page and it links using "git submodules" to the first docs repo

Normally AHK v1 commits are carried through to AHK v2.
But what if you know a commit applies to AHK v1 only, any procedure?

any procedure for what?

[jeeswg]

Re. multiple repos. OK I think I've figured it out.
The 2 folders here have '@' signs, so are relative folders:
GitHub - Lexikos/lexikos.github.io
https://github.com/Lexikos/lexikos.github.io
v1 @ 0c552bb
v2 @ bfcfd17

And they link to specific snapshots of the v1/v2 docs:
(You can see the short-form hashes match the long-form hashes in the urls.)
GitHub - Lexikos/AutoHotkey_L-Docs at 0c552bb976cc6bc279b0302326cf29595ce3ec5b
https://github.com/Lexikos/AutoHotkey_L-Docs/tree/0c552bb976cc6bc279b0302326cf29595ce3ec5b
GitHub - Lexikos/AutoHotkey_L-Docs at bfcfd17673fdd1970b7b2deb453f7326b05b22b5
https://github.com/Lexikos/AutoHotkey_L-Docs/tree/bfcfd17673fdd1970b7b2deb453f7326b05b22b5

---

Re. changes to the AHK v1 source code/docs, that shouldn't be moved onto the AHK v2 equivalents.
I.e. should you leave an informal comment to remind the devs to omit it in the next AHK v1-to-AHK v2 merge?
Or is there some git command to mark a commit as not to be merged into other branches? Thanks.

[guest3456]

Re. changes to the AHK v1 source code/docs, that shouldn't be moved onto the AHK v2 equivalents.
I.e. should you leave an informal comment to remind the devs to omit it in the next AHK v1-to-AHK v2 merge?
Or is there some git command to mark a commit as not to be merged into other branches? Thanks.

there is no command to mark a commit to not be merged. either you want to merge an entire branch, or you don't. you could leave a comment, but that would still require manual intervention. it looks like they just merge them through pull requests, and then manually go over the docs and edit them as appropriate:

https://github.com/Lexikos/AutoHotkey_L-Docs/pull/386