Skip to content

Commit adce50f

Browse files
jshackell-sfdcjshackell-sfdc
authored
Merge pull request #35 from salesforcecli/jshackell-templates-v2
fix: udpate the templates for sf
2 parents 251091f + b9b14ea commit adce50f

6 files changed

Lines changed: 48 additions & 65 deletions

File tree

‎templates/base_ditamap.hbs‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,5 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
1919
{{#if []}}<topicref href="{{[]}}" format="ditamap" scope="local"/>{{/if}}
2020
{{/each}}
2121
<topicref href="{{xmlFile 'cli_reference_help'}}" type="concept" format="dita" scope="local"/>
22-
<topicref href="../../sfdx_dev/workspace_setup/sfdx_dev_cli_deprecation.xml" type="concept"
23-
format="dita" scope="local"/>
24-
<topicref href="../../sfdx_setup/sfdx_setup_other_plugins.xml" type="concept"
25-
format="dita" scope="local"/>
2622
</topicref>
2723
</map>

‎templates/cli_reference_help.hbs‎

Lines changed: 38 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ THIS FILE IS AUTOGENERATED. DON’T MAKE CHANGES TO THIS FILE IN PERFORCE! YOUR
99
IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR DETAILS.
1010
1111
-->
12-
<title>Help for Salesforce CLI Commands</title>
13-
<shortdesc>The <codeph otherprops="nolang">-h</codeph> | <codeph otherprops="nolang"
14-
>--help</codeph> parameter shows details about Salesforce CLI topics and their
15-
commands.</shortdesc>
12+
<title>Help for <codeph otherprops="nolang">sf</codeph> Commands</title>
13+
<shortdesc>The <codeph otherprops="nolang">-h</codeph> and <codeph otherprops="nolang"
14+
>--help</codeph> flags show details about <codeph otherprops="nolang">sf</codeph> topics and
15+
their commands.</shortdesc>
1616
<prolog>
1717
<metadata>
1818
<othermeta content="concept" name="topic_type"/>
@@ -23,56 +23,43 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
2323
</metadata>
2424
</prolog>
2525
<conbody>
26-
<p>For namespaces, the <codeph otherprops="nolang">-h</codeph> | <codeph otherprops="nolang"
27-
>--help</codeph> parameter lists all topics in the namespace. For example, to see names and
28-
descriptions of all topics in the <codeph otherprops="nolang">force</codeph> namespace, run
29-
<codeph otherprops="nolang">sfdx force -h</codeph>.</p>
30-
<p>For topics, the <codeph otherprops="nolang">-h</codeph> | <codeph otherprops="nolang"
31-
>--help</codeph> parameter lists the commands and their descriptions. For example, to see
32-
all commands in the <codeph otherprops="nolang">org</codeph> topic, run <codeph
33-
otherprops="nolang">sfdx force:org -h</codeph>.</p>
34-
<p>For commands, adding the <codeph otherprops="nolang">-h</codeph> | <codeph otherprops="nolang"
35-
>--help</codeph> parameter shows parameters and usage information. For example, to see help for
36-
the <codeph otherprops="nolang">org:create</codeph> command, run <codeph otherprops="nolang">sfdx
37-
force:org:create -h</codeph>.</p>
38-
<p>Help for commands has four parts.<ol>
26+
<p>The short <codeph otherprops="nolang">-h</codeph> flag shows a subset of the command-line
27+
help and is meant for quick reference. The long <codeph otherprops="nolang">--help</codeph>
28+
flag shows the complete command-line help. </p>
29+
<p>The short help (<codeph otherprops="nolang">-h</codeph>) for commands has these parts.<ol>
3930
<li><b>Short Description of Command</b><p>At the top of the <codeph otherprops="nolang"
40-
>--help</codeph> output (with no heading), a short description of the command is
41-
shown. For longer descriptions, see the <cite>Salesforce CLI Command
42-
Reference</cite>.</p></li>
31+
>-h</codeph> output (with no heading), a short description of the command is shown.
32+
</p></li>
4333
<li><b>Usage</b><p>The command signature on the Usage line uses the docopt format.<ul>
44-
<li>All available parameters are listed. Parameters that have short names are listed
45-
using their short names.</li>
46-
<li>Parameters that take a value show the value’s type (for example, <codeph
47-
otherprops="nolang">&lt;string></codeph>) in angle brackets immediately after the
48-
parameter’s name.</li>
49-
<li>Optional parameters are in square brackets (<codeph otherprops="nolang">[ …
50-
]</codeph>).</li>
51-
<li>Required parameters have no annotation.</li>
52-
<li>For parameters that accept a limited set of values, the values are shown after the
53-
parameter name, separated by pipes (<codeph otherprops="nolang">--parametername
34+
<li>All available flags are listed. Flags that have short names are listed using their
35+
short names.</li>
36+
<li>Flags that take a value show <codeph otherprops="nolang">&lt;value></codeph>
37+
immediately after the flag’s name.</li>
38+
<li>Optional flags are in square brackets (<codeph otherprops="nolang">[ …
39+
]</codeph>).</li>
40+
<li>Required flags have no annotation.</li>
41+
<li>For flags that accept a limited set of values, the values are shown after the flag
42+
name, separated by pipes (<codeph otherprops="nolang">--flagname
5443
value1|value2|value3</codeph>).</li>
55-
<li>Mutually exclusive options are shown in parentheses, separated by a pipe (<codeph
56-
otherprops="nolang">( … | … )</codeph>).</li>
57-
</ul></p><p>If the command takes varargs (name-value pairs that aren’t parameters), the
58-
usage signature includes <codeph otherprops="nolang">name=value...</codeph>.</p><note
59-
type="tip">To see all Salesforce CLI commands, run <codeph otherprops="nolang">sfdx
60-
commands</codeph>.</note></li>
61-
<li><b>Options</b><p>The Options section lists all the command’s parameters, including their
62-
short name, long name, and purpose. For parameters that accept a value, the value name
63-
is written after an equals sign (<codeph otherprops="nolang">=</codeph>). The equals
64-
sign is optional when you run the command—for example, you could run <codeph
65-
otherprops="nolang">sfdx force:org:create
66-
<varname>-f=config/enterprise-scratch-def.json</varname> -a TestOrg1</codeph> or
67-
<codeph otherprops="nolang">sfdx force:org:create <varname>-f
68-
config/enterprise-scratch-def.json</varname> -a TestOrg1</codeph> with the same
69-
results.</p><p>Parameters that accept a limited list of values include the values in
70-
parentheses, with the default value indicated by an asterisk (<codeph
71-
otherprops="nolang">*</codeph>).</p><p>For more information about the parameters, see
72-
the <cite>Salesforce CLI Command Reference</cite>.</p></li>
73-
<li><b>Description</b><p>Usage notes and examples are below the list of parameters, in the
74-
Description section. This information is also available in the <cite>Salesforce CLI
75-
Command Reference</cite>.</p></li>
44+
</ul></p></li>
45+
<li><b>Flags</b><p>The Flags section lists all the command’s flags, including their short
46+
name, long name, and purpose. Flags are grouped for easier reading, such as global flags
47+
and other groups relevant to a specific command. </p><p>For flags that take multiple
48+
values, you have two ways to specify the values:<ul>
49+
<li>Specify the flag multiple times, where each flag takes a different single
50+
value.</li>
51+
<li>Specify the flag one time, but separate all the values with a space.</li>
52+
</ul></p><p>For example, the following commands are
53+
equivalent:<codeblock otherprops="nolang">sf deploy metadata --metadata ApexClass --metadata CustomObject --metadata AnotherCustomObject
54+
sf deploy metadata --metadata ApexClass CustomObject AnotherCustomObject</codeblock></p><p>Flags
55+
that accept a limited list of values include the values in parentheses, with the default
56+
value specified with the <codeph otherprops="nolang">default</codeph> keyword. </p></li>
57+
</ol></p>
58+
<p>The long help (<codeph otherprops="nolang">--help</codeph>) for commands has the same parts
59+
as the preceding short help <codeph otherprops="nolang">-h</codeph>) and these additional parts.<ol>
60+
<li><b>Description</b><p>Usage notes. </p></li>
61+
<li><b>Examples</b><p>All examples include a brief description.</p></li>
62+
<li><b>Flag Descriptions</b><p>Some flags have optional additional usage notes.</p></li>
7663
</ol></p>
7764
</conbody>
7865
</concept>

‎templates/cli_reference_xml.hbs‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,8 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
1010
1111
-->
1212
<!--This is a static file that should be passed as-is through the autogen process.-->
13-
<title>Salesforce CLI Command Reference</title>
14-
<shortdesc>The command reference contains information about the Salesforce CLI commands and
15-
their parameters. </shortdesc>
13+
<title>sf</title>
14+
<shortdesc>This section contains information about the <codeph otherprops="nolang">sf</codeph> commands and their parameters. </shortdesc>
1615
<prolog>
1716
<metadata>
1817
<othermeta content="reference" name="topic_type"/>
@@ -24,8 +23,8 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
2423
</prolog>
2524
<refbody>
2625
<section>
27-
<p>This version of the command reference includes details about version
28-
{{cliVersion}} of Salesforce CLI and the following plug-in versions:</p>
26+
<p>This version of the <codeph otherprops="nolang">sf</codeph> command reference includes details about version
27+
{{cliVersion}} of the <codeph otherprops="nolang">sf</codeph> executable of Salesforce CLI and the following plug-in versions:</p>
2928
<ul>
3029
{{#each pluginVersions}}
3130
<li><codeph otherprops="nolang">{{name}}</codeph> version {{version}}</li>

‎templates/command.hbs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
3939
format="html" scope="external" type="new-window:HTML">{{trailblazerCommunityName}}</xref> group in the
4040
Trailblazer Community.</note>
4141
</section>{{/if}}{{#if isOpenPilotCommand}}
42+
</section>{{/if}}{{#if isOpenPilotCommand}}
4243
<section>
4344
<note>We provide the <codeph otherprops="nolang">{{name}}</codeph> command to selected customers through a pilot program
4445
that requires agreement to specific terms and conditions. To be nominated to participate
@@ -58,7 +59,7 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
5859
</section>{{/if}}
5960
{{#if help}}
6061
<section>
61-
<title><ph>Help for <codeph otherprops="nolang">{{name}}</codeph></ph></title>
62+
<title><ph>Description for <codeph otherprops="nolang">{{name}}</codeph></ph></title>
6263
{{#each help}}
6364
{{#isCodeBlock this}}<codeblock otherprops="nolang">{{this}}</codeblock>{{else}}<p>{{this}}</p>{{/isCodeBlock}}
6465
{{/each}}
@@ -78,7 +79,7 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
7879
</section>
7980
{{/if}}
8081
<section>
81-
<title><ph>Command Syntax</ph></title>
82+
<title><ph>Usage</ph></title>
8283
<dl>
8384
<dlentry>
8485
<dt><codeph otherprops="nolang">{{binary}} {{name}}</codeph></dt>
@@ -90,7 +91,7 @@ IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR D
9091
</section>
9192
{{#if parameters}}
9293
<section>
93-
<title><ph>Parameters</ph></title>
94+
<title><ph>Flags</ph></title>
9495
<dl>
9596
{{#each parameters}}
9697
<dlentry>

‎templates/topic_ditamap.hbs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ THIS FILE IS AUTOGENERATED. DON’T MAKE CHANGES TO THIS FILE IN PERFORCE! YOUR
88
IF YOU WANT TO CHANGE THIS CONTENT, CONTACT juliet.shackell@salesforce.com FOR DETAILS.
99
1010
-->
11-
<title><codeph otherprops="nolang">{{topic}}</codeph> Namespace</title>
11+
<title><codeph otherprops="nolang">{{topic}}</codeph> Commands</title>
1212
<topicref href="{{xmlFile 'cli_reference' topic 'commands'}}" type="concept" format="dita" scope="local" chunk="to-content" collection-type="unordered">
1313
{{#each commands}}
1414
<topicref href="{{xmlFile 'cli_reference' command}}" type="reference" format="dita" scope="local"/>

‎test/unit/endtoend.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,6 @@ describe('plugin-login', () => {
4646
});
4747
it('creates parameters', async () => {
4848
const dita = loadTestDitamapFile(join('login', 'cli_reference_login_org_jwt_unified.xml'));
49-
expect(/<title><ph>Parameters<\/ph><\/title>/.test(dita)).to.be.true;
49+
expect(/<title><ph>Flags<\/ph><\/title>/.test(dita)).to.be.true;
5050
});
5151
});

0 commit comments

Comments
 (0)