 Gwyddoch chi? Allright, hello. Good afternoon. Thanks for coming down. I have been into the Python Room as a visitor before, but I've never spoken here, so I'm kind of excited. Yay, and I'm getting some cheering, and so like, hi! Ha ha ha ha ha! So my name's Lorna, my day job is kind of irrelevant, but I'll confess to being a developer advocate at Nexmo, because they're pretty cool people. Occasionally, I'm an RST to PDF contributor. I only have commit access because you need it to close issues on GitHub, and I go around closing stuff we're never going to get to, so the people that write the code can get on and do the important stuff. All the issues that I chose and left open, depending on your point of view. So let me introduce you to RST to PDF. It is an open source project. It's written in Python, which is clearly the best language. It's a tool that accepts a text-based markup format called restructured text, and outputs PDF. I use this for all kinds of stuff, basically anything that needs to look nice, but doesn't need to be edited, perhaps really must not be edited, such as your CV or resume, if you're sending it to a recruiter. I also use it for all my slide decks, including this one. I'm a developer advocate. This is my fourth talk in three days. I make a lot of slide decks. RST to PDF really makes this process scale and look, well, I'm not really a designer, acceptable. You can do a lot with the styles. So let's begin by talking about restructured text, and then we'll talk a bit about PDF, and then we'll talk more about the project as well. So in my opinion, restructured text is the king of markup formats. Probably you're familiar with a few others. Markdown seems to be ubiquitous, but if you want to do anything cool, you need lots of extensions and plug-ins, and we end up writing github markdown or different flavours. With a Python audience, I'm guessing quite a few of you are already familiar with restructured text. It's a little bit more fully featured than markdown. You can do a lot more out of the box, but it's a similar kind of idea, and I've got some examples to show you. There are others. I quite like ASCII Dock, but I think it's just a little bit closer to being a specialist domain, and that can make it more of a hurdle for people to contribute for engineers to write documentation. You can go the whole hog, leitech, dockbook, I've written them all. Restructured text is my favourite. The best thing about a text-based markup is that you already have a favourite text editor, and I'm guessing you're pretty much a power user. So you don't want to use proprietary tools, and nor should you. You're already doing awesome. You already have the tools that you need. Also because it's text-based, you can put things in source control. I know I'm preaching to the choir, but I'm not going to let the opportunity slip to mention what a good idea source control is. Captive audience, let's just mention it in passing. Source control is for people who sometimes make mistakes, don't like losing the work they've already done, and may, at some point now or in the future, work with other people. Pro-tip, if you've slept since you did the other half of this project, you are the other people. I would strongly recommend source control as a good way of giving yourself a checkpoint to go back to. You don't have to push your code to GitHub, just initialise Git locally and keep on committing to it. It is good practice and it will save you someday. You're welcome. Let's look at some restructured text examples. Here's the source for the first slide in this slide deck. It's got a title. Those double-bactics give you a fixed-width font. It's like a literal style. And there are some bullet points. The links link themselves. And then right at the bottom, you can see I've got a PDF directive to give me a different template on the next page, saying that's my title page directive, which is defined in the style file. You can put code blocks in. You just need to say what language is in. This appears later in this deck. And you can put images in as well and specify their width or height. I'd recommend width for slides because if you need to change the aspect ratio, things go wrong. Something like this for images, too. I didn't have any images in this deck. I'm not very image-heavy in the way that I work. Now you've had a little look at restructured text. You're going to use your text editor. You're going to use source control. Pretty approachable. Let's talk about PDF. A lot of people see PDF as the thing you export to. Perhaps something that you downgrade to for moving a backup or having to upload something to somewhere. I love to present from PDF. The clues in the name, portable document format. It works everywhere. The backup stick that is in my pocket will run on your machine, your machine, your machine. Maybe you're all using different operating systems. It doesn't matter. The images are in the file. The fonts are embedded. Everything will work. Perhaps you think that PDF viewers are not a way to deliver a presentation. I don't have enough hands for this. Let's try. This is my speaker view. I have this slide, next slide, timing, just like the keynote or Google Slides presentations do. These tools exist for Linux, for Mac. I'm having the same experience as all the other speakers on the circuit. Definitely recommend. I really like it. It makes it easy for me to work, to share tools, to back things up, to upload to both PentaBARF and noticed that I'm currently using the slides. That's not the best thing about PDF. It's cool for me. I am enjoying it. That's great. The cool thing about PDF is it's a standard. Other people have made tools that do awesome stuff with PDF. It means that I'm working inside an ecosystem that can really help me to do great things with my presentations. I use PDF.TK for manipulating PDFs. The next slide is not what you are expecting. There's another one later, which clearly doesn't belong in this deck. PDF.TK allows me to concatenate or manipulate files from other presentations into this deck. It's something that I've always used to put cover sheets onto handouts. You've got PDF, PDF.TK is your Swiss Army knife. PDF.Jam is a one-trick tool, those are the best tools, right, that makes a handout. You just say whether you want it portrait or landscape, how many this way, how many this way. You can configure the margins and stuff which can be helpful if you're printing it. PDF.Jam will give you a handout. I'd like to mention PDF.PC. That's giving me the speak of you that I just attempted to wave at you on my laptop. That didn't scale, but I've got screenshots online that you can look at on the RST to PDF website. I've got everything that any other speaker has. I've got an example of the handout. I get something like this. You can see this doesn't look the same as the style that I'm currently presenting with. The make file generates the dark theme that you want to use, the light theme, which I could use in a projector emergency and what uses less ink when you print it. It also generates an alternative version that you'll see in a minute, and it generates from the light version just different styles, same content, the handout. So I can just put this through the printer. If you print four slides across and three slides down on an A4 sheet of paper in landscape and black and white printer and you can still read all the words, well done! You've created a good presentation, your contrast is good enough and your fonts are good enough. That's just a little tip. So PDF.TK put this slide here. It obviously didn't, I didn't compile this here. PDF.TK chopped it up and put it here. OK, so RST to PDF itself. Everything you need is here, RST to PDF.org. You're going to install it with PIP. So PIP install RST to PDF. If you want to, you can grab the source. It's a Python project. I'm guessing you know what to do with that. We also have installation instructions. Python's not my home community. Even I can install it from source. So it's pretty easy going. This project is now actively maintained. It's had a bit of a gap, but it's something that you can expect to be around for a while. I feel it's not something that's widely known. And so I was pleased to be allowed to come and tell you all about a cool tool that might make your life a little bit easier someday. So how do you do it? You type RST to PDF and then the file that's got the RST in it. I'm not sure why I'm here. This is basically everything you need to do. You don't need me to tell you anything else. You can supply styles here. It comes with some styles that you probably don't want to use, but would get you going. It also cascades. So you can add a style and then another style and then whatever. So you can have a style that you use for everything and then some special overrides if you want to. I keep the styles for my slides and then the syntax highlighting separately. So I usually add two styles every time, but you can add as more as many as you need to and it just, the last one overrides anything that went before. So it's very easy to control. You can give it some instructions about layouts, which way around the page should go. I also use a switch, which is dash B, which says you should break on this level of title. So for the slide decks, you break every time you see a top level title. When you're working on a document with different chapter levels, you can configure that to whatever makes sense for the project that you have in hand. Keeping your content and your style separate is incredibly, incredibly useful. I have no idea why anyone would not choose this approach for everything that they do. I'm sure all of us have to do similar but different projects outputting documents or slides from time to time. By having a style that's applied at build time, I know that it's going to be consistent all the way through the project. I don't have to go and check that all the headings are the same size or if I add something, try and copy the other text box and then just edit the text to try and make them look the same. It just applies a style, so I know it's going to be consistent and it's going to make me look like I had great attention to detail. I didn't, but it doesn't matter. Styles can be reused between documents. If you look at my noticed page or my old speaker deck stuff, you'll notice they look pretty similar. I've got some favorite styles going on, but I don't need to work to reapply those styles to my content next time. I just write new content and then the style can be reused. We can flip that the other way round too, right? Because if I need to reuse content, then I just copy the RST content from one file to another and recompile it. Yesterday I gave a talk about webhooks in the PHP room. I had 25 minutes. Tomorrow I'm flying to Miami and next week I'm giving a talk about webhooks at the PHP conference. I have 60 minutes. There's some overlap there, but I can just create two presentations and then if I iterate on one and I want to move the content over, or if I give a similar talk in a month's time, I can just pull the content that I want and it will be seamlessly styled, even if I've chosen a completely different style for that deck. So you can take the same RST to PDF source. You can imagine a page that's got the same title, the same content, the same bullet points, but a completely different style applied. And there's basically no work involved. I hope you're all admiring my choice of Sniglet font. It's one of my favourites. Wallpaper, fixed width. The source for these slides looks the same. The way I built this was I have one RST source file that contains the content. I have three styles. I compile three different slide decks and PDFTK says, right, I want slides one to 14. Oh yeah, and I put the handout one in as well. One to 14, then I want slide 14 from that other deck. Now I want the rest of the presentation. You can just splice it together. I'm not sure why you would want to do this. Sometimes I try and do it live and just recompile with a different slide deck, but I thought I wasn't going to be able to use my machine, so we've got it spliced in. But it's a good example of how working in a standard file format like PDF opens the door to all sorts of things. You can make things behave differently for odd and even pages. You can hide whole sections when you don't need them. I've got a book on Lean Pub, which is created with hidden sections. It's a certification guide, so there's the questions and then there's the questions with all the answers and explanation and everything. It's a single source file because it's enormous and I'd hate to maintain two files. It's all in one place and I just hide the bits I don't need when I generate the questions doc. It's very easy to restyle. Eric was laughing at me recompiling my slide deck because I had the wrong one of these restyled. It's not unusual for me to recompile my slide deck in that I've got 90 seconds, I can do it, moment. When I get here, I mean not here, but I go somewhere and the contrast on the projector is terrible or the red doesn't seem to show up and you've got all pink titles. I'm relaxed about recompiling because I do it all the time in that moment before I go on stage. I do have a backup, it's in my pocket, I promise. But it's something that I just feel it gives me a lot of flexibility. It's not hard work to make it change or to repurpose the content. It's text based, you can grep for it. I mean I didn't give that many talks last year but in 2017 I gave 30. Where is the one where I talked about the... Yeah, you can find it, it's text based. It's searchable, it's easy. I find it a very convenient way to work. As an extra bonus and this is a dig at the JavaScript based presentation tools the tool itself is separate. It is not in your repository or your Dropbox or wherever you keep your documents or presentations. It's a separate tool, it's just installed on your machine. You're not copying that over every single time you create a new document as well. So, we create, we've got this, we've got this. Okay, code samples. It's Python, it uses pigments, everything is perfect. I've spent a long time using tools from other ecosystems and trying to bolt pigments on the side. This one's made of Python, everything is great. So you can just put your Python code in and there's a choice of pre-made the pigments themes. This is fruity, I hope you like it. And I've just stolen some code from one of the next more Python examples. This is how you receive an SMS in case you're interested. But you can also then restyle this however you want. I have a sort of pastel-ish theme that I use on a dark background which is pretty similar to the xoria theme that I use in Vim myself so it's quite easy to look at. And still quite high contrast. Cool, so let's talk about the project while I've got a little bit of time left. RST to PDF is an open source project. The current version is 0.94 and that was released 24th of January 2019, so about a week ago. The previous version, 0.93, which is what you'll get if you install from app or whatever, is 19th of December 2012. We went six years with no release. This project had a single maintainer and I think he, I don't know, lost faith that we loved the tool and appreciated the work that we did. And it went a little bit inactive for a while. It's been rebooted because Rob, who's up here and will answer any technical questions you have, foolishly volunteered to help out. And Roberto, who's project it was originally has also jumped back in. So we've got quite a lively set of maintainers and quite a lot of activity on the project. This new release is just the first of a few that you should see. So if you're interested, please follow along. Open issues talk to us. We do have people active on the project at the moment. I am mostly closing issues, answering questions and writing website documentation. So if you have questions, you probably get me in the first instance, but if it needs fixing, we have people for that too. The stages of the project, is still Python 2 only. Since we became maintainers, the test suite exists and all the tests pass, which seems like a good place to start from for any sort of major surgery. So we are ready to receive new contributions to the project. We're all set up for that. I feel like the tests pass on three, but the tool doesn't really work or something. I feel like it's close. We have experience of migrating from two to three, and you would like to make the world and the open source projects a better place. That would be lovely, come and talk to us. We've started a new website. The documentation is now available obviously in PDF. Also in HTML, it might be a bit more manageable. I'm working on a suite of examples. So if you would like to see an example of something that you don't see there, open an issue, I'll do that one next. I'm kind of working through a wish list because I'm happy to have you jump the queue to get your examples live as you need them. I mentioned the test suite, and I am always asked how you test a PDF. You generate a PDF that you're happy with, right? So human takes PDF, looks at it and says, aha, yes, that is what I was aiming for. Then we create a hash of that file. When we come to run the test suites on mass, the machine creates the PDF and hashes it and makes sure that the hashes match. In fact, we have a few known good hashes because if you have different dependencies, different report lab, different inkscape, you get slightly different file hashes. So we have a list of known good ones. We also have a dodgy piece of code that attempts to visually, not visually, have image magic compare the images and tell us if they're the same. It's all very exciting. So if you're into that kind of thing, cool, I am kind of running out of time. RST to PDF, use your text editor, create a PDF. RST to PDF.org. I've got some resources for you, so that's the main website, the GitHub project, a cool, restructured text sheet, wow, from Roberto, who's also a maintainer on RST to PDF. Some links for me in case you are interested. Do I have time for questions? Yeah, okay. Does anyone have any questions? Yeah. How is it different from latech? So I used latech with the beamer packages and text live for a long time. RST to PDF is much more approachable as a markup format, which hopefully comes across in the examples. I'm also finding it a lot easier to style because my styles are just like, no, I want the margins to be this size, I want the font to be like this, whereas I never really masked, like somebody else wrote my styles for beamer and I never really figured out how to edit them. So I think this, I can do all the same stuff, but I'm finding this much more approachable, just more easier for me. Cool. That's a good question. You'll have to shout. Yes, you can have headers and footers. So this is my footer here, and you can also have different templates per page. So some of my title pages don't have a footer because they're actually a different template. So you can have those as you need, and it's clever about page counter and odd and even pages. You can have some different stuff for those. No, they're not specified in HTML. You put them at the top of your file as a specific class, and then they appear on each page. Cool. Yep. What's missing for version one? Python 3 support, probably. We don't know why it never went to version one before we got it. So we released 0.94 as a, like, hi. We've learned, Rob's learned how to package for PyPI. So, you know, we're on track. I think you'll see... I might be speaking out of turn here. I'm going to do it anyway because I've got the mic. You might see a 1.0 release on the Python 2 branch and then a 2.0 on the Python 3 branch, just in case for any reason we need to fix on the 2 branch. So that's the tentative plan, really a good reason. Cool. Anyone else? Yeah, you also need to shout. Sorry, I can't hear you. Okay, so does it have a live preview while you're working on the RST? It doesn't, but I have the build on a Vim macro, and if you use skim on Mac, or... I can't remember. Anyway, one of the Linux machine, they'll live reload the PDF as it changes, so I don't miss it. So not really, but kind of. Rob? There's a live reload Vim plugin that does it when it's saved. I'm out of time if you have more questions. Come and talk to us now. Thanks for coming.