
PowerShell and Markdown - nailer
https://ephos.github.io/posts/2018-8-1-PowerShell-Markdown
======
wildebaard
While I get that it's easy to hate on and make fun of Microsoft, why _not_
applaud them for making stuff like this that apparently is 'a given' in the
linux-world.

What's wrong with a good idea, even if, especially if, others are already
doing it. It's not like stealing IP; it's about making tooling nicer.

I for one actually like this (granted, I use PowerShell regularly).

~~~
alsysadmin
I get sick of all the downplaying that PowerShell gets. I find interacting
with the console a breeze, and just as usable as Bash. I can easily perform an
ad-hoc API call into an Object, explorer it and export it into a well
formatted .csv file for a report in minutes.

We use it in tooling for tons of things that would otherwise be done in Python
and have no issues. Especially once you get it set up on Server Core and run
the jobs in Cron.

I just don't get all the negativity towards it. There's a reason so many
vendors are providing great PS modules for their products: VMWare, AWS, etc.

~~~
xienze
I think it boils down to a lot of people having a fundamental misunderstanding
of what makes PS different than Bash, i.e., not understanding how significant
it is to have processes communicate through piped objects versus piped text,
which is far more brittle.

~~~
makecheck
Since it is impossible to force all inputs to be well-constructed, text acts
as the more predictable interface. Once I learn a bunch of command-line tools
for processing text, I know exactly how to compose commands _or_ post-process
text from a file _or_ extend the usefulness of a program that doesn’t happen
to produce output I want.

While there may be something “brittle” from time to time, in my experience
this just means it was _possible_ to tackle the problem with text when the
alternative would have been to have no way to do it _at all_.

PowerShell feels like it wants everything to be structured perfectly, and
“perfect is the enemy of the good” applies. Sometimes, I don’t _care_ if there
is a way to perfectly structure a particular input because many use cases just
don’t have stringent requirements.

~~~
xienze
> Since it is impossible to force all inputs to be well-constructed, text acts
> as the more predictable interface.

Disagree. If the program decides to change its output formatting even by a
small amount (like going from a GNU version of the program to the BSD version,
where such things can happen), e.g. changing the column order of two items,
whoops, your script is broken. When you deal with object versus textual output
the textual representation of a program can change all day long and you're not
affected. The only breaking change is a change to the output object format
(like renaming or deleting properties).

Writing scripts that rely on text being output in a specific order with a
specific format is very brittle in my opinion.

~~~
makecheck
Robust scripts require diligence appropriate for the environment. If you’ve
deployed systems with different default tool versions, you factor this in,
e.g. by installing a common version that both can use (or just make scripts
that can figure out how to work either way). Two versions of a tool isn’t
really any different than two versions of a compiled-in API, except that APIs
tend to be more rigid (not always, e.g. some languages allow runtime
querying).

There’s a common rule in Unix-like systems that essentially says “inputs are
liberal, outputs are conservative”. It matters to have programs that can
adapt, because this makes a lot of things more practical.

------
JdeBP
> _Using Show-Markdown you can take markdown and display it as a VT100 encoded
> string right in the console._

This is an erroneous description (which in fairness originated with Aditya
Patwardhan of Microsoft not with the author of the headlined article here, who
is just parrotting it). As Thomas Dickey points out, VT100s had no notion of
multiple colours at all. This is not VT100.

* [https://github.com/PowerShell/PowerShell/pull/6926](https://github.com/PowerShell/PowerShell/pull/6926)

* [https://invisible-island.net/xterm/xterm.faq.html#what_vt220](https://invisible-island.net/xterm/xterm.faq.html#what_vt220)

> _It just feels… odd._

M. Pleau rightly points out the odd division of labour in the commands, here.
Oddly, the conversion command not only generates an abstract syntax tree
object, it also (but _optionally_ ) renders that AST into HTML _or_ text with
ECMA-48+T.416 control sequences. The "show" command then picks one of those
two renderings from its input.

A more conventional division of labour would have been one tool to create the
AST, another tool (or indeed tools) to render the AST into HTML and
ECMA-48+T.416 text, and the usual already existing PowerShell tools to
paginate/display HTML and ECMA-48+T.416 text.

(I add T.416, by the way, because the examples include T.416 SGR control
sequences for indexed colour. Interestingly, they use it for a reverse video
effect, for which there already was an ECMA-48 control sequence: SGR 7/SGR
27.)

------
nailer
Recent comparison of pwsh to bash - finding out if you have the compromised
eslint plugin. It's a bit apples-to-oranges, also I would have used 'find
-exec {}' in the bash example, but it's still interesting:

bash (by Feross):

    
    
        find . -type d -name "eslint-scope" -print0 | xargs -n 1 -0 -I % sh -c "(cat %/package.json | npx json version) && echo '(at %)'" 
    

pwsh:

    
    
        $results = @{} 
        ls -recurse -filter "eslint-scope" | foreach { 
            $file = "${_}\package.json" 
            $version = cat $file | convertfrom-json | select -ExpandProperty version $results.Add($file,$version) 
        } 
        echo $results | format-list 
    

I quite like the Powershell version, even though the syntax is unfamiliar.
$results is a real hash object, the JSON tools are built in and formatting is
up to you (you could have it output Excel or markdown if you wanted). I don't
really like '_' as the iteration variable but otherwise I prefer it.

~~~
userbinator
It's interesting how different opinions on the syntax are --- the extreme
verbosity and "general bureaucracy" of PS is one of the things that puts me
off using it unless there's really no other way. It feels like a weird mix of
C#/Java, perl, and bash. Reading-Lots-OfWords_With-CapitalisationLike-This is
just plain annoying. Perhaps because it reminds me of posts on various forums
from users who would capitalise the first letter of every word.

~~~
oblio
You're being unnecessarily mean.

First of all, there's no _ in sight in regular identifiers (99,99%). They're
always CamelCase and Kebab-Case when including the verbs.

Secondly, it's case insensitive so you don't even need to go CamelCase. Just
lowercase-itallthewaytothebank :D

Thirdly, it depends on what you want to do. You can use $_ and % and various
Perlish shorthands for faster CLI usage, but it's your call. You don't have to
mix, you can go full C# and just use the names or go full Perl and use the
shorthands, it's up to you.

And fourthly, that bureaucracy makes things very discoverable. Now you're used
to bash, but bash & ecosystem suck hard the first few months, until you
accumulate the baggage, sorry, the knowledge to use them proficiently :)

~~~
pweissbrod
When powershell 1.0 came out I LOVED the concept of piping objects like so
much streams. In my experience there were two camps of powershellers, the
scripters and the programmers.

The scripters, probably the more experienced folks would use abbreviations,
shorthand and all-lowercase. The programmers like myself would predominantly
use powershell on less-frequent occasions to glue our apps together and
PascalCase and verbosity has already been burnt into our brains.

Powershell, like perl, took that philosophy that welcomed both parties to
write code as they pleased.

But then powershells 2 and 3 and 4 came out, and all that stuff I learned in
v1 became deprecated. And I wanted a powershell script that would just
reliably run on any, say, windows machine 2003 or beyond. But when I google
for something like 'how do I invoke an osql.exe query command? how to escape
the quotes?', or, 'how to load a dll and having an adjacent config file and
run a method?' I get so many different answers ranging from woefully misguided
to version-specific to syntax so wildly different to the untrained eye they
look completely different yet being effectively equivalent. I inevitably spend
hours crawling google and cobbling together the bits that work cross-platform,
document heavily and sit in amazement at how much work it took to do something
one would think was simple.

It's a shame but my experiences with powershell as an occasional user have
shifted from enthusiasm to seeing it as an arcance even punishing experience
when I'm used to bash or python.

I hope this doesnt sound mean in any way, its just that when youre talking
with a computer, words like grep/sed/awk and regular expressions bear a
learning curve but once you get past that barrier it is much easier to
communicate succinctly with the computer with what you really want to do.

~~~
Someone
The various Unixes had growing pains there, too. They took 20 to 40 years to
get at a state where all _grep_ s behaved more or less the same, and they
haven’t even reached a state where regular expressions are standardized.

------
nailer
This really needs a 'ConvertTo-Markdown' to match 'ConvertFrom'. In the same
way we have ConvertTo-Json, ConvertTo-Html, ConvertTo-Csv, etc.

That would allow your powershell script's object to be shown as pretty
markdown tables.

------
brad0
There's a great tool called mdv on macOS if you're interested in using this in
the mac terminal

[https://github.com/axiros/terminal_markdown_viewer](https://github.com/axiros/terminal_markdown_viewer)

------
forgotpwd16
In a more general tone, is anyone using PowerShell on Linux? Indeed it has
some good ideas going on and its syntax seems well received from its Windows
users, but since having gone cross-platform I haven't seen any comments on
using it on Linux besides plain comparing it to bash.

------
DarkWiiPlayer
It's 2018 and microsoft is still re-inventing the wheel in the most useless
way possible. As a linux-user, I almost take it as a given that I can just
display markdown in the terminal (in my case, using vim) and in the windows
world it's apparently a totally new concept.

~~~
evfanknitram
In Windows there's been a lot less emphasis on the terminal since most
functionality has only been configurable using the UI. This is changing now.

Your post is a little like complaining over a functional programming language
adding OO-features or vice versa and saying they are late to the party.

~~~
DarkWiiPlayer
I'd agree with that if windows was less bloated. If it was an acceptable
position that it never had good terminal support because it did one thing and
did it well, and that thing happened to be GUI, then yes, why bloat it with
useless shell features that their user base doesn't need. Instead, windows has
always been filled with features nobody wants _or_ needs (looking at you,
Internet Explorer 10), and most of them are way larger and probably took more
development effort than it would have been to just build a good terminal
emulator.

~~~
JdeBP
You're rather missing the fact that Windows does not have a terminal I/O
model. It has a _console_ model. Consoles are what the 1960s terminal model
_evolved into_ during the 1980s; from firmware-mediated access to CGA, through
the VIO+KBD+MOU subsystems of OS/2, to Windows NT console objects.

* [http://jdebp.info./FGA/tui-console-and-terminal-paradigms.ht...](http://jdebp.info./FGA/tui-console-and-terminal-paradigms.html)

------
kyleperik
I don't understand the usefulness of Microsoft investing time in writing a
built in half finished markdown rendering engine. With Linux these things just
pop up and get popular as people get used to them. Feels like Microsoft is
trying to just woo developers on the fence.

~~~
forgotpwd16
This a preview version so half-baked features are to be expected. More to
point, from the PR, according to one of the collaborators "[t]he goal here is
to open the way for native supporting help files in Mardown format. So
currently [they] only need "convert from Markdown" and rendering. Later [they]
could add other cmdlets." It seems Microsoft plan is to make a `man` (or
`info`?) system but using a sane language instead.

~~~
kyleperik
Thank you for the thorough explanation.

Still seems odd, as markdown by definition isn't really meant to be displayed
in a terminal.

Markup: "the process or result of correcting text in preparation for
printing."

This further confirms my suspicions about Microsoft's motives. If they wanted
to make a `man` system, they would have made one, instead of working on
markdown in the terminal which sounds quite trendy amongst Linux users.

------
eltoozero
So PowerShell has an integrated dingus[0] now eh?

So, where’s the equivalent offline bash script zero dependency sed awk
contraption that is the reason we don’t get “nice things” in our trusty
workhorse shell.

Or is the answer to “quick” offline markdown to html conversion on Mac/Linux
“install pandoc”?

[0]:
[https://daringfireball.net/projects/markdown/dingus](https://daringfireball.net/projects/markdown/dingus)

~~~
toyg
The whole point of markdown is that you don't need a renderer in terminals.

~~~
nailer
Sure, but if you want pretty headings, links, bold text etc - there's now
'show-markdown'

