Thank you for all right, thank you for your parations,
everybody. Hi, my name is Luna. I'm here because I love documentation,
the command drawing, and the first them are equally.
So this is like everything I love, all the number you're over here, everything is wonderful.
We started a bit right and I already have massively too much content,
so this is going to be amazing.
Thank you for joining me on this adventure.
So, now I'm continuing to talk about the command drawing.
It's not new, it's not sexy, but it's a tool that I come out live without
in my documentation projects. My background is in software engineering.
I've been a Linux user for many years.
I run just with this up front.
I am a good user.
I am not sorry.
But I really think the command drawing has helped me enormously,
and I'm going to share a little bit of this with you.
If you are new to the command line, great.
Please don't imagine that you're going to need the ring,
knowing of the magic incantations.
This stuff is hard, but that can show you that you're candid,
and giving something you can remember,
so that you can look at that later,
then I have one and so have you.
And then you can learn why I'm the calls,
it lets me use the same tools everywhere.
The stuff that I'm using in development,
I can then automate into CI.
It'll run on my machine, your machine, and somewhere else.
Most of what I'm using today is very, very mainstream tools,
so they will work across all of the Unix Linux family.
You should be fine on OSX as well.
When those, if you're using WSL, you will be fine.
Everything else, look at these words,
and you'll find the alternative tools that are available.
So they should be pretty transferable.
You'll see my skills.
Don't go out of date nearly as quickly,
as every other tool that's in fashion every year.
So I am just still using the same things that I've been using for years,
and they're very, very familiar to me.
Come on, our text, you can search for them.
You can easily look up what the command does,
which is harder with the button that's like,
it looks like a bit of a picture of a hand,
but the finger, how do you search that?
There are also really, really scriptable.
So you can write a script that does a complicated series of options,
and maybe use the config file and does things in a sequence,
and you can use that and reuse that on this laptop,
the next laptop, someone else's laptop,
and again maybe in your CI setup.
I use it loads for batch operations.
So if you're using program as editor or an IDE,
in the tools are fine on small docs projects.
You know, you've got 100 files or 1000 files,
like it's quite manageable,
but when you're doing those bigger docs projects,
the might span multiple repositories,
they're probably owned by different teams,
some of them came into acquisition,
and you have 10,000 files or 100,000 files,
these are the tools that will let you handle that,
and I hope I've got something that will help you.
On a very personal note,
I also have some accessibility needs.
It cannot use a pointing device of any kind.
I can only use the keyboard.
I genuinely think the CLI is a productivity hack for everyone,
but I'm not an expert because I'm hardcore,
I literally have no choice.
So let's talk about the study of magic lessons
with some of the reusable ingredients
that you are going to see all the way through this talk.
First, the redirect operator,
it's the pointy bracket in the middle.
On the left, I have the list command,
and on the right, I'll file name,
the output of the list command gets redirected
into the file name.
I wrote that we do on the command line,
combines stuff together,
so you're going to see this one a lot.
We got the pipe operator,
take that output,
and instead of putting it into a file name,
give it into the next command,
and I'm going to start showing you things
that you can slot into the different commands.
Why do we need this?
Each CLI tool traditionally,
the established ones, do exactly one thing,
and they do it really well.
And that means that one tool
doesn't wound the functionality of another tool.
We don't make one tool that does all of the things.
We just put together,
build the blocks of the tools that we want to use.
You're also going to hear a lot about regular expressions.
I hope you already know something about regular expressions,
because that is a different talk.
And I am absolutely definitely not giving that talk today.
There is not time.
But you're going to see some of that stuff in the talk,
so as a tiny,
like the smallest possible introduction,
have a look at these three expressions.
The first one,
I'm searching for the letter H,
then any character,
that's the dot,
it's a wild card.
The asked wrist means as many as you want,
and then the letter P.
So this will match hip,
but we can have multiple letters,
so it will also match.
And we are allowing spaces,
so it will match anything that starts with an agent into the P.
The second one,
with the second flex,
or character,
that anchor's it to the start of the line.
You'll also see dollar for an anchor
to the end of the line.
Sometimes you don't want to randomly match in the middle.
You want to be seriously,
it starts like this.
And that will match the or theatre,
or anything else that starts with that.
Finally, I have a find and replace,
and you're going to see this as well.
Replacing every equal signs with that line.
The such G is for global,
do it everywhere.
Some people in the room just already guessed
that I use RS,
it restricts a text a lot.
But this is how you change the heading levels.
So there's a bunch of things here
that you will see.
Again, I can't teach you regular expressions in five minutes,
or less.
It is the apprenticeship takes a lifetime,
but hopefully you'll at least know what you're looking at,
and you'll know what to search for it now.
Right.
The first set of tools I want to show you,
help you to find your way around a project.
You've seen the list command.
You can list with a selection of wildcards.
But I was preparing this talk.
I decided that I would definitely,
you know, I would put together a slide deck,
and you'd be able to refer to it later.
I actually want to show you a slide deck at all.
So let's just jump straight into the command.
Is this big enough?
If you are at the back,
you can read this.
Thank you.
Good.
So this is, I have the Veil source code lying around
on my hard drive.
So we're using the Docs I found in the Veil source code,
because I mostly do Docs projects with places working,
and I am currently between jobs.
I don't want to embarrass anybody.
I now don't work for.
So we'll just use the open source project
that we all know and love.
This is the Veil Docs.
I'm not running the preview locally,
but you can,
and they're on their Docs are in sort of live content.
Good.
These are the files that are in this folder,
and I use LS loads to anchor myself,
and look at the next level down.
I got some files.
I also got some directory,
so the yellow ones without file extension.
Good.
So far, not groundbreaking.
If I just want to see the mark down files,
then we can do that,
and that's what I'm mostly interested in.
We're talking about Docs.
There are a bunch of things I do with LS,
because it has a lot of functionality.
Here it is with the long list format.
The load of our W's, things on the left hand side.
These are the file commissions.
Then we've got the owner and the group.
This can be important if you don't have access to a file,
you should have, or it's got written by something.
It can be useful.
The columns between my name and the date,
is the size.
So I can easily tell from this listing that one of these files is empty.
I find that slightly lower.
We're not fixing the docs,
we're just running commands against using this as the example.
So maybe we can look at this together,
as I'm going to show us contribution later.
Then, and it sorts alphabetically by default.
There's a caveat about case sensitive systems,
but it sort of is alphabetically by default.
So my time has locked itself.
This is going really well.
Good.
I might not want it sorted alphabetically.
How do you feel about doing it sorted by time instead?
So you can see the most recent edit at the top there,
and then all the ones further down.
I've apparently updated this clone quite recently, so.
Yeah.
Good.
Except, this is never what I want when I'm sorting by time,
because if there's a lot of files in the directory,
and you want to look what you just modified,
those need to be here at the bottom where you can see them.
So instead, we will just reverse this and have a quick look what changed.
So this is how you find your way around.
I use this stuff a lot.
So a bit wrong I mentioned, although.
So next, let's have a look at the command called tree.
This is tree.
There's a bit more of it, but essentially, you get the idea.
This shows you directories with the files inside.
It helps me to get a sensor.
You know, there's a list of all these innocuous directories,
but two, you know, they've all got eight files in,
except this one that's got 800 files in.
A lot of useful to know.
So tree lets you see the shape.
As a documentarian, the other time that I use tree.
Is to give a representation of a file structure in documentation,
to show someone how it should be set up.
If you don't have a fancy file representation plugin feature
in your docs platform, you can put this in a code snippet
and everybody will understand it.
So for read these things, it's a really nice tool to use.
Alright, let's look at how to count lines.
Now the file for the command for counting lines is obviously called WC.
Because we allowed developers the name things.
No, it's the word count utility.
But the word count lines and words and bytes,
or sometimes characters, it's usually bytes.
So I'm going to count just the lines on the index file.
Let's go 100 and 22 lines.
Here are a sense of how big that is.
We can run this.
Let's do word count for all the metrics on all the markdown files.
Oh look, now I've got, so that's left hand column is lines.
I've got words and then I've got bytes.
So still got that empty file looking at me.
No, I don't know why that's there.
So if there's one file, but huge, you would know.
And you can also use this in different directories to start
to get a sense of how big this is.
Also if you are writing to a word count,
the word count utility can be quite useful.
And obviously you can batch that up.
What else did I want to tell you about that?
I think this is a good start on the tools that I use
from a structure perspective.
Looking at what do we have?
How is it shaped? How big is it?
Where is it? How is it spread out?
This little set are very mainstream commands that you see all the time.
And I use them all the time. I hope you will use them all the time.
All right, so now we're under some slightly more advanced magic.
And I would like to show you a command called grep.
You might have seen it. Grep now.
It's a verb.
You grep for something.
Technically it isn't.
It's like an acronym and it stands for global regular expressions
such in print. Really?
Tell me ages to learn that instead of something.
It's just a word. Grep. Grep.
It's a verb.
Regics. It's a noun. That's it.
You're dangerous words.
So the grep command is how we search for and find things.
So let's have a look at these amount down files.
So I'm pretty confident there'll be some headings in these amount down files.
And I would like to look at all of the files.
All the lines that start with the hash or pound sign.
I'm pretty sure I'm going to say hash in other Englishes.
You might say pound whatever.
So stop talking. Let's type.
So I'm going to grab recursively for lines that start with.
There's the circumflex.
Here's my pound sign.
And let's just do all the files.
Here's some files.
I expected this to be the headings.
But looking at it.
No, all of those are headings.
I think that we've got here is a selection of.
Comments inside codes and if it's inside marked out files.
So how about to make it easy for demo purposes.
I'm going to change the assignment.
Let's find all of the.
Um, top level subheadings.
So two hashes.
In each file.
Grep again.
So I need start of the line. I need two hashes.
And it is space.
Otherwise we're going to go.
So two hashes and three hashes and four hashes.
We're going to return them all.
So let's see how many second level.
Um, headings the raw.
That looks better.
Yeah.
I'm convinced that that's what I wanted.
And how many were there?
804.
Pretty nice.
Okay.
So we can start to look then with Grep at the characteristics of the files that we work on.
Other things that I enjoy are.
Um, if you have a look at this.
Um,
Mark down.
Then it uses this style of linking.
So instead of pasting URLs all over the.
Uh, serves.
It links to a number and then the number is defined within the file.
You've seen this in other formats.
It's valid in Mark down as well.
Oh, and let's get a list of these.
And I can get that by graping for.
Start the line.
A square bracket.
Some digit.
Another square bracket.
And that probably get them all.
So let's try.
And the way that I do this is our build it up.
So I'll start with like right.
Let's try.
I'm going to grab for a square bucket.
A one.
This is a different.
My normal.
Keyboard.
Try again.
A square bucket.
It's how special meanings in rejects.
And I literally mean a square bucket.
So let's get it with the one.
And the escape.
And let's.
And then anything.
I want that to start the line.
Otherwise it makes no sense.
And.
Okay.
Wow.
I was going.
Okay.
But I would like the other numbers as well.
And.
So I'm going instead of the one.
I'm going to take that out and allow a range of numbers.
So now you can instantly index all of the links that are in your docs.
Because grep can find them all.
You can put them here.
You can change the outputs.
You can format what grep gives you back.
It can give you just a list of files.
I often use grep to give me a list of files.
And I put the list of files in a file.
And it becomes like the source of truth.
For either scripts that operates on everything.
Or.
Maybe it goes into a spreadsheet as like these are the work items that we need.
These are the files identified that have problems.
So there's lots of things that you can do where this will make it much quicker.
Than even your finding files or something like that in the GUI tools.
One more thing.
I'm going to be very quick.
I've shown you grep and I feel morally obliged to show you said as well.
Said is how we after we find.
We use it to replace.
You're going to use said on the day that your boss comes to me and says,
Okay, we rename the product.
Update the docs now.
We've already brought out the best release.
Go.
Said is that amazing finder replaced.
You're going to use it when you change the syntax.
You use the annotations.
You're going to change it when you use a different plugin for a code snippet.
Those incredible blow your mind.
Big scale changes.
You're going to do that with said.
Probably.
I also want to show you some dip tools because I think that's very important.
We have to go very fast as a while as a large amount of shout at me.
So I'm going to copy this file and we're going to make an original of it.
So that I can dip because I just said I would show you.
This is said.
We're going to do a find and replace.
So I'm going to use the dashi.
We've rebranded bail.
I'm sure they won't mind.
Now it's called fail.
Good.
So let's replace all of the instances of bail with fail.
In this one file so that it's not massive.
All right.
So what happened?
We can dip these two files.
Let's start with the original.
We'll have a little look at the diff.
You can see that there are some changes.
This is not the nicest way to look at changes.
You need this your homework.
Find a dip tool that you love on your platform.
I'm going to use it.
You've been dip a lot.
It shows me the changes in a really nice format.
I can turn on wrap.
It locks the two halves together.
And I'm going to use it.
So I don't need to think my fingers know how to move.
And you can push and pull the changes between versions.
If you have versions that have drifted apart for any reason.
These are the tools that will help you a lot.
There are also very good graphical tools.
I use meld sometimes.
Here, again, you need to look this up for your operating system.
But it's the same sort of thing in a slightly more human-friendly format
with scrolling slightly less terminal type things.
Cool.
So whatever you just did, don't say it, right?
Good.
So we've made a lot of changes.
However, I don't know if you noticed.
But we definitely did stuff we should not have done.
This is not going to work.
I should not have done this here.
I should only have replaced where it was at word.
So I'm not teaching you get today.
But anyway, we're just going to undo those changes.
So I can have another go with my said command.
What I should have done is chosen bail as at word.
So that slash B is the word boundary.
So it will find four stops or new lines or spaces or whatever.
It looks like bail by itself.
Then we'll do the replace.
Good.
We talked a little bit about the dip tool already.
But remember, I'm editing a file that's under source control.
You just watch me reset the changes.
Get Diff.
It's slightly nicer than Diff.
But this is not something that inspires me to gush about the functionality
in a bar, honestly.
And so what you need to do is take that favorite Diff tool
that I told you to choose.
And instead, hook it up to get.
So that when you run it, you get your Diff tool of choice each time.
For a complex Diff, especially something like this,
where we've made a lot of small replacements in one file.
We did it automatically.
You can just come here as an easy way to eyeball stuff
and get it back together.
Managing changes and versions is a key skill.
Take the time to set things up whether you choose CLI tools or something else.
It's really important.
So I made it a slides.
We've seen LS.
You've seen tree for a representation.
You've seen the word count for counting lines.
We have gripped for things.
I have no idea why said is called said.
The reject stuff that we did with said,
you will find in all your editors as well.
So that will be fine.
We've talked about the Diff.
You need to configure, get to use a better Diff tool
than what comes with it for non-trivial changes.
I do not have time to talk to you about Pandok.
It's amazing.
Or the convert tool that comes with it is magic.
We're not going to build scripts today.
I have threatened on social media to write up the whole demo,
the content and everything as a little ebook or publishable thing.
So ping me if you would like to hear about that.
And we will do it.
You've seen a very small tip of an iceberg,
but you can do so much with the tools I have shown you already today.
I hope it gave you some ideas or things you could do with tools you know,
or new tools that you can apply to your projects.
I want to share some resources with you.
That's my blog.
I sometimes write about stuff.
The wizard's in-stuff has amazing,
and you're content people.
We do information.
Has amazing resources go there by all the scenes.
Write it up.
Has some good content as well.
Please remember for all your speakers.
The wizard has a feedback page.
It means a lot to us.
And as a side note,
I don't currently have a job,
so if you need me to do anything for you,
let me know.
Thanks so much everybody.
Thank you.