It is currently May 18th, 2024, 1:23 pm

Small docs suggestions

Discussions about the documentation, main Rainmeter site and forums.
User avatar
Yincognito
Rainmeter Sage
Posts: 7274
Joined: February 27th, 2015, 2:38 pm
Location: Terra Yincognita

Re: Small docs suggestions

Post by Yincognito »

Jeff wrote: June 12th, 2023, 11:46 am https://docs.rainmeter.net/developers/#SendMessage

Unless SendMessage has been deprecated because it has 0 popularity (beside RestartRainmeter.exe), the section of the page could benefit from having the queries listed from the rainmeter/Library/RainmeterQuery.h file, a direct link to the GitHub page should be more than enough
Adding stuff to the documentation is a very good thing, since that area is not exactly easy to understand or abundant in examples, just like the WindowMessage plugin (another victim of popularity). That being said, I urge against removing things from certain sections solely based on subjective opinions about popularity or the terrible modern illusion that popularity is synonym with quality and usefulness. For example, you can do things like these with the info on that page, and that's just a single instance where it can be useful.

I'm only saying this to avoid degenerating the talk from an optimal improvement of the docs to changing it in a manner that sacrifices comprehensiveness for popularity, all for the sake of keeping things "up to date". Just in case the discussion was heading in that direction, that is. If it was not, then no problem. ;-)
Profiles: Rainmeter ProfileDeviantArt ProfileSuites: MYiniMeterSkins: Earth
User avatar
Jeff
Posts: 334
Joined: September 3rd, 2018, 11:18 am

Re: Small docs suggestions

Post by Jeff »

Yincognito wrote: June 12th, 2023, 12:36 pm I'm only saying this to avoid degenerating the talk from an optimal improvement of the docs to changing it in a manner that sacrifices comprehensiveness for popularity, all for the sake of keeping things "up to date". Just in case the discussion was heading in that direction, that is. If it was not, then no problem. ;-)
It wasn't going in that direction, it was just my snarky way to interpret my experience that - before RestartRainmeter.cpp was added and I skimmed through it out of curiosity - I literally had no idea Rainmeter could even do that (I know about the same name plugin, I just didn't know Rainmeter had the system too) and had no recollection of anything up to that point that used that feature, hance the popularity part of my message. I'm gonna stop so it dosen't degenerate further.

The GitHub link can still be added to that section! I would propose something like "The majority of the queries along with their definitions are detailed in the source code."

(HTML code for easy copy pasting)

Code: Select all

<p>The majority of the queries along with their definitions are detailed in the <a target="_blank" rel="noopener" href="https://github.com/rainmeter/rainmeter/blob/d082c9cfee42eade0f13eaac283371576b6b738e/Library/RainmeterQuery.h">the source code</a>.</p>
User avatar
Yincognito
Rainmeter Sage
Posts: 7274
Joined: February 27th, 2015, 2:38 pm
Location: Terra Yincognita

Re: Small docs suggestions

Post by Yincognito »

Jeff wrote: June 12th, 2023, 1:52 pm It wasn't going in that direction, it was just my snarky way to interpret my experience that...
Ah, I see - I probably misunderstood where you were going with this. No worries, it's all clear now. :thumbup:
Profiles: Rainmeter ProfileDeviantArt ProfileSuites: MYiniMeterSkins: Earth
User avatar
Jeff
Posts: 334
Joined: September 3rd, 2018, 11:18 am

Re: Small docs suggestions

Post by Jeff »

I have 2 suggestions for the bangs page
  1. On the !WriteKeyValue entry, FilePath is considered as optional, however, it's required if you run the bang through the command line, that bit of info exists on the site only in the 1.3 patch notes.
    My suggestion to somewhat add the necesary info is doing something similar to the !SetWindowPosition bangs, where info about the parameters are below the example. In our case however, we just add an * after "optional" and below the example we add * Note: This option is required when executing the bang using the command line.
    Here is how it will look
    Image
    Here's the HTML for easy copy pasting, don't forget to add the * after optional though!

    Code: Select all

    <br><br><p>* <b>Note:</b> This option is required when executing the bang using the command line.</p>

  2. Rainmeter can execute more than what is presented with the command line as parameter option, it would be nice to give more examples, and maybe even hint the fact that you can load custom setting files with the features.
    I've put the info about the Config and * above the examples, and created a new header 2 for the section
    Image
    And again, the HTML for easy copy pasting

    Code: Select all

    <p>Many bangs have a <code>Config</code> parameter. Unless otherwise specified, valid values are the <a href="/manual/skins/#Config">config name</a> of a currently loaded skin to be acted upon or <code>*</code> (asterisk) to act on all currently loaded skins. When optional and not supplied, the parameter defaults to the current config. If executing a bang with a "config" parameter from the Windows command line, the parameter is always required.</p>
    <h2>Command Line Arguments</h2>
    <p>Bangs can also be used from the Windows command line as a parameter to the Rainmeter.exe executable. Examples:</p>
    <ul>
    <li><code>"C:\Program Files\Rainmeter\Rainmeter.exe" !RefreshApp</code>.</li>
    <li><code>"C:\Program Files\Rainmeter\Rainmeter.exe" !SetVariable foo bar "foobar\main"</code>.</li>
    <li><code>"C:\Program Files\Rainmeter\Rainmeter.exe" [!SetOption WelcomeStringMeter Text "Click to continue." "foobar\welcome"][!UpdateMeter "WelcomeStringMeter" "foobar\welcome"][!Redraw "foobar\welcome"]</code>.</li>
    </ul>
    <p><b>Note:</b> Any variable of any kind, including <a href="manual/variables/built-in-variables/">Built-In Variables</a> are not executed when calling Rainmeter from the command line.</p>
    <p>In addition, you can specify a custom setting file for the Rainmeter process to start with, the Skins folder becoming relative to the settings file's folder. Example: <code>"C:\Program Files\Rainmeter\Rainmeter.exe" ".\setting 1\rainmeter.ini"</code> (the file name dosen't need to be rainmeter.ini specifically).
    </p>
As a finishing note, I learnt the hard way [#SkinsPath] and other variables don't work in command line on !WriteKeyValue, I guess the only way to get those is really through Windows Messages magic. Oh well! That small slither of info should be modified with exact info though, by someone who knows better than me.
User avatar
Jeff
Posts: 334
Joined: September 3rd, 2018, 11:18 am

Re: Small docs suggestions

Post by Jeff »

According to this commit and the 4.5.12 version history, :GetOption has a third (optional) parameter. Seems like the Lua pages never got updated with this. Should be an easy fix though, just copy paste and change the wording from the release notes. Just adding
  If the optional boolean parameter bReplaceMeasures is provided, when set to false it will not replace any section variables before retrieving that option.  
should do it.
GetOption;;Parameters: OptionName, Default, bReplaceMeasure;;Returns the current value of the named option as a string. If the option does not exist, returns the given default value, or '' if no default is given.
If the optional boolean parameter bReplaceMeasures is provided, when set to false it will not replace any section variables before retrieving that option.
Example: MySolidColor = MyMeter:GetOption('SolidColor', '000000')
EDIT: For some some reason [dоc] broke
User avatar
jsmorley
Developer
Posts: 22633
Joined: April 19th, 2009, 11:02 pm
Location: Fort Hunt, Virginia, USA

Re: Small docs suggestions

Post by jsmorley »

Jeff wrote: August 27th, 2023, 9:23 pm According to this commit and the 4.5.12 version history, :GetOption has a third (optional) parameter. Seems like the Lua pages never got updated with this. Should be an easy fix though, just copy paste and change the wording from the release notes. Just adding
  If the optional boolean parameter bReplaceMeasures is provided, when set to false it will not replace any section variables before retrieving that option.  
should do it.
GetOption;;Parameters: OptionName, Default, bReplaceMeasure;;Returns the current value of the named option as a string. If the option does not exist, returns the given default value, or '' if no default is given.
If the optional boolean parameter bReplaceMeasures is provided, when set to false it will not replace any section variables before retrieving that option.
Example: MySolidColor = MyMeter:GetOption('SolidColor', '000000')
EDIT: For some some reason [dоc] broke
Done. Thanks!
User avatar
Yincognito
Rainmeter Sage
Posts: 7274
Joined: February 27th, 2015, 2:38 pm
Location: Terra Yincognita

Re: Small docs suggestions

Post by Yincognito »

Since I'm here now, something that has been bugging me for a long time, even though I don't use it: in the Partially Supported Players section of the NowPlaying page, there is:
Spotify: PlayerName=Spotify
Partially supported. Only the types Artist, Track and the bangs Play, PlayPause, Stop, Next, and Previous are available.
and it should be:
Spotify: PlayerName=Spotify
Partially supported. Only the types Artist, Title and the bangs Play, PlayPause, Stop, Next, and Previous are available.
Profiles: Rainmeter ProfileDeviantArt ProfileSuites: MYiniMeterSkins: Earth
User avatar
jsmorley
Developer
Posts: 22633
Joined: April 19th, 2009, 11:02 pm
Location: Fort Hunt, Virginia, USA

Re: Small docs suggestions

Post by jsmorley »

Yincognito wrote: August 27th, 2023, 11:20 pm Since I'm here now, something that has been bugging me for a long time, even though I don't use it: in the Partially Supported Players section of the NowPlaying page, there is:

and it should be:
Done, Thanks!
User avatar
Jeff
Posts: 334
Joined: September 3rd, 2018, 11:18 am

Re: Small docs suggestions

Post by Jeff »

jsmorley wrote: August 27th, 2023, 11:13 pmDone. Thanks!
I don't know how to put it lightly but the changes are weird, there are 2 GetOption on the page which both need to be changed, only the measure one got changed and now the measure one has an example about meters, the parameters also didn't get changed.
Sorry for the extra trouble created, here's the HTML code for easy copy pasting.

Line 235-239

Code: Select all

<dt id="GetOption"><code>GetOption</code> <small>Parameters: <code><b>OptionName</b><em>, Default, bReplaceMeasures</em></code></small></dt>
<dd>
	<p>Returns the current value of the named option as a string. If the option does not exist, returns the given default value, or <code>''</code> if no default is given. If the optional boolean parameter <code>bReplaceMeasures</code> is provided, when set to <code>false</code> it will not replace any section variables before retrieving that option.</p>
	<p><b>Example:</b> <code>MyGroup = MyMeasure:GetOption('Group', 'None')</code></p>
</dd>
Line 302-306

Code: Select all

<dt id="GetOptionMeter"><code>GetOption</code> <small>Parameters: <code><b>OptionName</b><em>, Default, bReplaceMeasures</em></code></small></dt>
<dd>
	<p>Returns the current value of the named option as a string. If the option does not exist, returns the given default value, or <code>''</code> if no default is given. If the optional boolean parameter <code>bReplaceMeasures</code> is provided, when set to <code>false</code> it will not replace any section variables before retrieving that option.</p>
	<p><b>Example:</b> <code>MySolidColor = MyMeter:GetOption('SolidColor', '000000')</code></p>
</dd>
User avatar
jsmorley
Developer
Posts: 22633
Joined: April 19th, 2009, 11:02 pm
Location: Fort Hunt, Virginia, USA

Re: Small docs suggestions

Post by jsmorley »

Jeff wrote: August 29th, 2023, 2:03 pm I don't know how to put it lightly but the changes are weird, there are 2 GetOption on the page which both need to be changed, only the measure one got changed and now the measure one has an example about meters, the parameters also didn't get changed.
Sorry for the extra trouble created, here's the HTML code for easy copy pasting.

Line 235-239

Code: Select all

<dt id="GetOption"><code>GetOption</code> <small>Parameters: <code><b>OptionName</b><em>, Default, bReplaceMeasures</em></code></small></dt>
<dd>
	<p>Returns the current value of the named option as a string. If the option does not exist, returns the given default value, or <code>''</code> if no default is given. If the optional boolean parameter <code>bReplaceMeasures</code> is provided, when set to <code>false</code> it will not replace any section variables before retrieving that option.</p>
	<p><b>Example:</b> <code>MyGroup = MyMeasure:GetOption('Group', 'None')</code></p>
</dd>
Line 302-306

Code: Select all

<dt id="GetOptionMeter"><code>GetOption</code> <small>Parameters: <code><b>OptionName</b><em>, Default, bReplaceMeasures</em></code></small></dt>
<dd>
	<p>Returns the current value of the named option as a string. If the option does not exist, returns the given default value, or <code>''</code> if no default is given. If the optional boolean parameter <code>bReplaceMeasures</code> is provided, when set to <code>false</code> it will not replace any section variables before retrieving that option.</p>
	<p><b>Example:</b> <code>MySolidColor = MyMeter:GetOption('SolidColor', '000000')</code></p>
</dd>
Sorry, see if it is right now...