Comments (24)
Same for about topics
from platyps.
So, adding in a sample help file. This is the text version. We need to create a simple MD schema for these, and then create a conversion mechanism.
TOPIC
about_aliases
SHORT DESCRIPTION
Describes how to use alternate names for cmdlets and commands in Windows
PowerShell.
LONG DESCRIPTION
An alias is an alternate name or nickname for a cmdlet or for a command
element, such as a function, script, file, or executable file. You
can use the alias instead of the command name in any Windows PowerShell
commands.
To create an alias, use the New-Alias cmdlet. For example, the following
command creates the "gas" alias for the Get-AuthenticodeSignature cmdlet:
New-Alias -Name gas -Value Get-AuthenticodeSignature
After you create the alias for the cmdlet name, you can use the alias
instead of the cmdlet name. For example, to get the Authenticode signature
for the SqlScript.ps1 file, type:
Get-AuthenticodeSignature SqlScript.ps1
Or, type:
gas SqlScript.ps1
If you create "word" as the alias for Microsoft Office Word, you can type
"word" instead of the following:
"C:\Program Files\Microsoft Office\Office11\Winword.exe"
BUILT-IN ALIASES
Windows PowerShell includes a set of built-in aliases, including "cd" and
"chdir" for the Set-Location cmdlet, and "ls" and "dir" for the
Get-ChildItem cmdlet.
To get all the aliases on the computer, including the built-in aliases,
type:
Get-Alias
ALIAS CMDLETS
Windows PowerShell includes the following cmdlets, which are designed for
working with aliases:
- Get-Alias. Gets all the aliases in the current session.
- New-Alias. Creates a new alias.
- Set-Alias. Creates or changes an alias.
- Export-Alias. Exports one or more aliases to a file.
- Import-Alias. Imports an alias file into Windows PowerShell.
For detailed information about the cmdlets, type:
Get-Help <cmdlet-Name> -Detailed
For example, type:
Get-Help Export-Alias -Detailed
CREATING AN ALIAS
To create a new alias, use the New-Alias cmdlet. For example, to create the
"gh" alias for Get-Help, type:
New-Alias -Name gh -Value Get-Help
You can use the alias in commands, just as you would use the full cmdlet
name, and you can use the alias with parameters.
For example, to get detailed Help for the Get-WmiObject cmdlet, type:
Get-Help Get-WmiObject -Detailed
Or, type:
gh Get-WmiObject -Detailed
SAVING ALIASES
The aliases that you create are saved only in the current session. To use
the aliases in a different session, add the alias to your Windows
PowerShell profile. Or, use the Export-Alias cmdlet to save the aliases to
a file.
For more information, type:
Get-Help about_Profiles
GETTING ALIASES
To get all the aliases in the current session, including the built-in
aliases, the aliases in your Windows PowerShell profiles, and the aliases
that you have created in the current session, type:
Get-Alias
To get particular aliases, use the Name parameter of the Get-Alias cmdlet.
For example, to get aliases that begin with "p", type:
Get-Alias -Name p*
To get the aliases for a particular item, use the Definition parameter.
For example, to get the aliases for the Get-ChildItem cmdlet type:
Get-Alias -Definition Get-ChildItem
GET-ALIAS OUTPUT
Get-Alias returns only one type of object, an AliasInfo object
(System.Management.Automation.AliasInfo). However, beginning in
Windows PowerShell 3.0, the name of aliases that don't include a
hyphen, such as "cd" are displayed in the following format:
<alias> -> <definition>
For example,
ac -> Add-Content
This makes it very quick and easy to get the information that you
need.
The arrow-based alias name format is not used for aliases that
include a hyphen. These are likely to be preferred substitute
names for cmdlets and functions, instead of typical abbreviations
or nicknames, and the author might not want them to be as evident.
ALTERNATE NAMES FOR COMMANDS WITH PARAMETERS
You can assign an alias to a cmdlet, script, function, or executable file.
However, you cannot assign an alias to a command and its parameters.
For example, you can assign an alias to the Get-Eventlog cmdlet, but you
cannot assign an alias to the "Get-Eventlog -LogName System" command.
However, you can create a function that includes the command. To create a
function, type the word "function" followed by a name for the function.
Type the command, and enclose it in braces ({}).
For example, the following command creates the syslog function. This
function represents the "Get-Eventlog -LogName System" command:
function syslog {Get-Eventlog -LogName System}
You can now type "syslog" instead of the command. And, you can create
aliases for the syslog function.
For more information about functions, type:
Get-Help about_Functions
ALIAS OBJECTS
Windows PowerShell aliases are represented by objects that are instances
of the System.Management.Automation.AliasInfo class. For more information
about this type of object, see "AliasInfo Class" in the Microsoft
Developer Network (MSDN) library at
http://go.microsoft.com/fwlink/?LinkId=143644.
To view the properties and methods of the alias objects, get the
aliases. Then, pipe them to the Get-Member cmdlet. For example:
Get-Alias | Get-Member
To view the values of the properties of a specific alias, such as the
"dir" alias, get the alias. Then, pipe it to the Format-List cmdlet. For
example, the following command gets the "dir" alias. Next, the command
pipes the alias to the Format-List cmdlet. Then, the command uses the
Property parameter of Format-List with a wildcard character (*) to display
all the properties of the "dir" alias. The following command performs
these tasks:
Get-Alias -Name dir | Format-List -Property *
WINDOWS POWERSHELL ALIAS PROVIDER
Windows PowerShell includes the Alias provider. The Alias provider lets you
view the aliases in Windows PowerShell as though they were on a file system
drive.
The Alias provider exposes the Alias: drive. To go into the Alias: drive,
type:
Set-Location Alias:
To view the contents of the drive, type:
Get-ChildItem
To view the contents of the drive from another Windows PowerShell drive,
begin the path with the drive name. Include the colon (:). For example:
Get-ChildItem -Path Alias:
To get information about a particular alias, type the drive name and
the alias name. Or, type a name pattern. For example, to get all the
aliases that begin with "p", type:
Get-ChildItem -Path Alias:p*
For more information about the Windows PowerShell Alias provider,
type:
Get-Help Alias
SEE ALSO
New-Alias
Get-Alias
set-alias
export-alias
import-alias
get-psprovider
get-psdrive
about_functions
about_profiles
about_providers
from platyps.
In markdown this seems to be pretty straight forward.
Heading
Content
Subsection Heading
Content
In the text file we can assume this:
- Anything in a text file without indent is some kind of heading.
1A) Headings in ALL CAPS is a 'Heading'
1B) Headings in mixed case is a 'Subsection Heading' - Anything indented is meant to be content.
Transforming that from MD to Text might be more tricky.
The headings convert without problem. The content however, needs to be indented, and it also need to wrap in an easy to read way and in the 80 or so character that make up the default width of a PowerShell console window.,. @vors @joeyaiello correct me if I'm wrong on that assumption.
from platyps.
@juneb's template https://github.com/juneb/PowerShellHelpDeepDive/blob/master/about_Topic_Template.help.txt
from platyps.
pushing this out, as it is additive and can be built in after milestone 0.4.0
from platyps.
Continuing this discussion here. After our cmdlets review, there were some take-aways:
All:
Thoughts on the following? @sankethka @vors @joeyaiello
0 - The will need to be a cmdlet New-AboutHelp, which converts .MD About to .txt. Also a New-AboutHelpTemplate, which generates a stub. (Not as sold on the stubbing idea, but throwing it out there)
1 - About topics should be linked to in the readme, but should themselves be separate .md files.
2 - About topics should have a one-way transformation. MD -> Text
3 - The transformation allows character width of 80 in a single line.
4 - UTF-8 encoding by default with optional param to override
5 - Each section is separated by a single blank line
6 - The name of the about.md will be transformed to .txt as about_{aboutTopicName}.txt
7 -
Using the template Sergei suggested above:
We have three kinds of headings:
About Topic Name
Subject Heading
Subtopics
from platyps.
The name of the Cmdlet you are proposing can indeed cause a confusion potentially. Since the task is primarily about conversion from MD to txt, perhaps our cmdlet name should be around that thought.
Also, the template generation is a good idea as this would help the self serve process easier.
from platyps.
I agree with @sankethka that this should be a general cmdlet that can use templates for specific uses.
Just FYI, I have an About topic template that you're welcome to use. https://github.com/juneb/PowerShellHelpDeepDive/blob/master/about_Topic_Template.help.txt
from platyps.
@juneb Thanks for the template! Let me talk with @vors about it :)
@Sanketha, @juneb - per renaming the cmdlets to generate a stub, how about this?
New-AboutHelpTemplate stays the same
The New-About Help folds into New-ExternalHelp which would process aboutTopic.md files and using the metadata with an about flag, would then create an about.txt instead of rolling the aboutTopc.md into the MAML?
from platyps.
@jongeller Perfect.
from platyps.
Thank you @juneb !
from platyps.
@sankethka @vors
Could I get you to take a look at commit f4463af
I'd like your thoughts on the aboutTemplate.md I created.
Also any feedback on the change to the build script is welcome.
from platyps.
@jongeller I would use pattern {{ Placeholder Explanation }}
to match existing templates for parameters.
from platyps.
good point, on it.
from platyps.
updated template, and a build script fix
also, now including pester tests in commit 10ececa
from platyps.
updated, template creation functionality added & it passes tests.
commit c1b7dba
from platyps.
@jongeller Template looks fine.... thanks.
from platyps.
updated to include About Topic rendering from MD to Txt, which adhears to the About Topic Schema above.
commit 17d0bbd
After CI passes, I will submit a pull request on Master branch.
from platyps.
@vors could you take a look, the most recent push to my AboutTopics branch failed CI: https://ci.appveyor.com/project/PowerShell/markdown-maml/build/0.4.0.652
This isn't happening locally. Is it possible CI doesn't have the updated help?
from platyps.
@jongeller it has WMF 5 and we call Update-Help
on init, so no, it's probably something different.
These looks like a legitimate problems to me:
[-] Validates attributes by checking several sections of the single attributes for Add-Computer 726ms
Expected string length 48 but was 24. Strings differ at index 0.
Expected: {Add the local computer to a domain or workgroup.}
But was: {{{Fill in the Synopsis}}}
-----------^
366: $mamlModelObject.Synopsis | Should be "Add the local computer to a domain or workgroup."
at <ScriptBlock>, C:\projects\markdown-maml\test\Pester\PlatyPs.Tests.ps1: line 366
[-] Validates the examples by checking Add-Computer Example 1 89ms
ArgumentOutOfRangeException: Index was out of range. Must be non-negative and less than the size of the collection.
Parameter name: index
at <ScriptBlock>, C:\projects\markdown-maml\test\Pester\PlatyPs.Tests.ps1: line 373
from platyps.
@jongeller it looks like you push your changes to master and broke the build
Now all Tim's PR are failing
I'm reverting your changes in master. Please don't do that in the future.
from platyps.
Sorry, I see what you did: made a dummy change in master and reverted it back to re-run tests on master in CI.
My appologies, @jongeller
I temporarily disabled this 2 tests to unblock you, #156 to track it
from platyps.
Pull Request #157 now submitted to close this issue.
from platyps.
Tests working successfully, merged into master, now closed.
from platyps.
Related Issues (20)
- New-ExternalHelp should be able to create MAML from markdown that uses the new schema HOT 1
- New-YamlHelp needs to convert the module.md file to YAML HOT 1
- Unable to detect markdown file HOT 1
- New-MarkdownHelp provides unclear error when module as no commands
- Support for data from XMLdoc for binary modules
- Parameter Sets with 0.14.2 HOT 1
- 🚀 [Idea]: Support adding titles to examples HOT 1
- Create new cmdlets for creating Cab/Zip files for updateable help
- After updating version of platyPS (from ) creating new external help file is throwing error
- HelpVersion parameter support
- Update-MarkdownCommandHelp should have the ability to skip update of module markdown file
- Export-YamlCommandHelp should create module folder structure
- Support module files with multiple H2 for grouping cmdlets
- Protect certain frontmatter metadata fields
- Support unordered list of links under RELATED LINKS
- [V2 test] New-MarkdownCommandHelp incorrect metadata in module file
- [V2 test] New-MarkdownCommandHelp not honoring -HelpUri and -HelpInfoUri
- [V2 test] PS> Import-MarkdownModuleFile need to transform "Download Help Link"
- [New-ExternalHelp] Generate incorrect MAML file if example includes []
- Supress ProgressAction parameter from New-MarkdownHelp output HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from platyps.