GitHub: contributing to the AutoHotkey documentation

Discuss Autohotkey related topics here. Not a place to share code.
Forum rules
Discuss Autohotkey related topics here. Not a place to share code.
User avatar
jeeswg
Posts: 6904
Joined: 19 Dec 2016, 01:58
Location: UK

GitHub: contributing to the AutoHotkey documentation

27 Nov 2019, 06:51

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/[email protected] · 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/[email protected] · 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
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
guest3456
Posts: 3053
Joined: 09 Oct 2013, 10:31

Re: GitHub: contributing to the AutoHotkey documentation

30 Nov 2019, 23:58

jeeswg wrote:
30 Nov 2019, 23:40
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
jeeswg wrote:
30 Nov 2019, 23:40
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?

User avatar
jeeswg
Posts: 6904
Joined: 19 Dec 2016, 01:58
Location: UK

Re: GitHub: contributing to the AutoHotkey documentation

01 Dec 2019, 00:36

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.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
guest3456
Posts: 3053
Joined: 09 Oct 2013, 10:31

Re: GitHub: contributing to the AutoHotkey documentation

01 Dec 2019, 08:48

jeeswg wrote:
01 Dec 2019, 00:36
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


Return to “General Discussion”

Who is online

Users browsing this forum: BNOLI and 30 guests