 So I'm Sean, I'm going to talk to you about Mallard and a whole pile of tools that have evolved around Mallard. So Mallard is a documentation format. It is a topic-oriented format, it is a radically topic-oriented format. It grew out of the GNOME project when about 10, 15 years ago we decided we wanted to throw away all of our books and go topic-oriented in all of our help. So it's quite different than how other topic-oriented formats work or other systems work. Usually you write some topics but then you write some sort of assembly or map that still puts them into a linear book-like structure and Mallard doesn't work anything like that. It happens to be XML, but I'm going to talk about that in a minute. And it's a semantic format, but it's not too semantic. It tries to strike a nice balance with simplicity. In some formats like DocBook or DDA, they might give you this whole pile of options for, this is a function name or a variable name and Mallard just gives you the code element or a UI button versus a UI menu item. I never need this distinction, so we just have a GUI element. So you still have those semantics, you're not just saying bold or monospace, but it's a fairly simple set of semantics. So I'm going to mostly do live demos, so I might sit a little bit. This is a Mallard page. The top unit of information is a page in Mallard. We have some metadata here. Some of the stuff like these links, those are super important and we're going to talk about it. Some of it's just some nice bookkeeping. You can track some extra information. There's a title, there's a paragraph, there's a section. It's all the kind of stuff you would expect from a format. Here's some of our inline markup. I said we had the GUI element. There's our semantic element for that. And we have the semantic elements for block things. So here's a note. And here's a funny if test thing that I'm going to talk about in about two minutes. So we have a fairly simple semantic XML vocabulary. What kind of stuff can we actually do with it? So one of the things that we have is a tool called Yelp Check. And here's a bunch of commands it can do. You can validate your pages or check for broken links or broken image references. You can get a report of the status of each page so you know if it's release ready. So that's one of the cool tools we have. Usually though you just want to publish, right? So we have Yelp build and we can take that. I'm going to output to a directory I've already made. Create some HTML. That just takes a couple of seconds. I'll throw balls while it takes a couple of seconds. And, okay, here it is. It was generated. We can go to some actual page here. You see that note. This is the page we were just looking at the source for. So sections and links and all of that stuff. And then, actually within GNOME though, we don't actually build out DHTML. We actually just install the mallard stuff. And we run a tool called Yelp. This is the built-in help viewer in GNOME. If you ever pull up the help for any application, this is what you're going to see. And you can see it shows you the exact same stuff, right? So this is how we do this. And Yelp is actually reading the mallard stuff, rendering it on the fly. This is very powerful because it allows us to do things like runtime conditional processing, which I will talk about very, very soon. So, all right, that was Yelp check and Yelp build and Yelp. So how do, how does this work? How do we do all of our linking? You'll notice that, right, I clicked down from the index page, down into that the logout page. And we had links going back the other direction. Hang on. I'm going to delete a page because I'm going to make it later. So, we clicked into this page. We have a link down here into the logout. This has a link in turn back up to the top-level index page here. It also has up at the link trail at the top. There's a link to it as well. And so, how does all that linking work? So, if we look in the shell exit page here, we've got these links here in the info. They're metadata links. And we're saying we have a guide link that's going to the index page and some advanced stuff you don't have to worry about. If we actually look at index.page, that's that front page. Front page in mallard is always called index. It has, this is not a trivial guide page. It has some stuff going on. But of all the stuff it has going on, at no point does it have a link to shell exit.page, which is the page we actually linked down to. In fact, it doesn't have any links at all. And this is the really critical feature of mallard that differentiates it from everything else, is that it has this automatic linking structure. So, you create your navigational structure with these guide and topic links. It's kind of your up and down through the navigational structure rather than writing any sort of assembly or a map that gives you a tree. And these links, whenever you define them, they always work in both directions. It's always automatic. And there are other types of links like see also links that move kind of horizontally across the document. Those also work in both directions. So this, first of all, it really changes the way you assemble your documentation, the way you think about it. When you work with mallard, you tend to write topics for things that people want to do. You write those topics first and then you kind of assemble them from the bottom up rather than starting with this top-down hierarchy and filling things in. It also enables some really neat features that you don't find other places. So if you have an application that has a plugin architecture, your plugins can ship help pages that plug into your help just like the plugin plugs into your application. So you can see your plugin help right there alongside your application help. It's also nice if you have distributions or other downstreams that are redistributing your code and maybe they're adding some features. They can drop in help for those features without having to actually patch anything. They can just add pages to the doc set. So that's how the links work. I'm going to actually, I'm going to prove they work. So I'm going to go back to the shellexit.page. I'm going to make a new page. I'm going to do it just by copying this one, pasting it here. I need to have a unique ID. So I'll say shellexit again. Just make it easy to identify, log out, power off or switch users again. And then I'm going to save this. shellexit again.page. So I've created a new page. It happens to have those same links because I just copied and pasted. But I didn't modify index.page at all. And if I pull this up and yelp, I notice right here, there's the page that I just added. So all of the linking structure works automatically. Okay, so I mentioned the conditionals. I don't want to talk about those. So you notice these are in a different namespace. If you know XML syntax, that would be familiar. So mallet is extensible. We can create extensions to it. And the conditional processing is done as an extension, but it's a core extension and it's supported and everything. And what we're doing here, GNOME ships with a different mode called GNOME Classic. It's built on GNOME 3 technology, but it looks more like GNOME 2. Sometimes we have to write different docs for that, right? Because it looks different. So what we're saying here is, if the platform is GNOME Classic, well, then we want to do this. If it's not GNOME Classic, we've got this little negation here, then we want to do this other thing. And so the conditional processing can actually do negations. It can do ands and ors, full logical expressions. It's extremely powerful. So going with all the extensions, I'm going to get incredibly way more complicated in just a 20-minute talk because why not? I'm going to go over to the Getting Started page. Let me load that up again. So this page has some videos on it. These are thumbnails. You click on them. It brings up the video. It's kind of cool. We've got these subtitles running down here. And the subtitles are not inside the video. They're actually inside the page, which is kind of cool because it means we can translate them along with all the rest of our content that's in our documentation instead of them being locked up in a video, which is much more difficult to translate. And so what does that look like? There's too many pages here. So this gets a little more complicated in the markup, of course. We've got the conditional processing happening again. But this time there's this choose and when. There's a whole branching structure you can use if you want to get very advanced. The overlay thing that gave us the thumbnail and the pop-up thing, that's in an extension. So that's why it has the UI. But the video, that's in Core Mallard. So video is supported out of the box. There's a thumbnail going on. And then there's all this TTML. And you notice here the namespace on that is on w3.org. So we didn't make a subtitle format. The W3C made a standard subtitle format. And we're able to take an existing standard XML vocabulary, drop it directly into our XML. And in fact, we then mix Mallard into the TTML that's sitting in our Mallard. So you see we have our Mallard GUI element sitting inside of our TTML. So that's all cool. We can embed TTML. We can embed SVG. It's very neat. There's also here this ITS translate. ITS is the Internationalization Tag Set. It's also a W3C standard for providing information about how to translate a document. And so we translate all of our documentation using a tool called ITS tool. It allows you to do XML to PO and back again. And everything it knows about a particular XML vocabulary, it knows from this W3C standard format there's rules that define how things work. And so we're able to work with that. And ITS tool, by the way, if you're doing XML translations, you should be using it. It's not just a Mallard tool. It'll do DocBook or DDA or XHTML or TTML or SVG or any other XML that you can write ITS rules for. All right. So that's a whole bunch of XML. I've shown you the linking structure. I've shown you how we can actually embed. I've gone straight up to the most complicated example of embedding other vocabularies into it. So it's very powerful in its ability to do that. And a lot of that power comes from the fact that it's XML. One of the nice things about XML is that it provides you kind of a data model for how things are fit together instead of just being a syntax for telling you to format this one way or another, right? You get sort of a tree of your content and so you can do these kinds of things. The problem with XML is that it's XML and it's extremely verbose, right? Every time you do an element, you have to write the name of the element twice because you have to open it and close it. And so can we have a compact syntax, a lightweight syntax that gives us all the power of what we can do with Mallard and with XML. And the answer is yes. So I'm going to switch over to a fairly straightforward XML file. Here's a page. It has a title. It has a paragraph. It has steps. That's just a list of things that you should be doing. It has items in it. This item has a paragraph and also a note, right? So it's not just one paragraph in there. We have some examples. We have down here terms. That's like a DL in HTML or a variable list in DocBook. These items have multiple paragraphs and examples and then more paragraphs. So what does that look like? Here it is. Here's those steps. Here's that list inside of the steps, examples. Here's our terms list with multiple paragraphs and examples, all of that stuff. So DuckType is a syntax that is designed to do Mallard and do literally everything that Mallard can do with a compact syntax that will be familiar to you. I mean, it's not going to be exactly Markdown, of course, but if you've used Markdown or ASCII Doc or restructured text or textile or wikis or other sorts of compact syntax, it's going to have that kind of familiar structure. So here's that exact page converted into DuckType. Here's the title. That's a pretty familiar syntax. All that stuff in the info is with this at syntax. So we can do all of the metadata, which is really important because, remember, those linked metadata elements are just critical to how Mallard works. We come down here. Our paragraphs are delineated with a blank line, which is, I would say, the defining feature of a compact syntax, right? And then we're able to do these semantic block elements. Here's that steps. We do it with this kind of square bracket syntax and it introduces the block thing. We've got the items. And now here we have, this is important, we have that note sitting inside of the item. And a lot of compact syntaxes don't allow you to nest or nest very deeply. And so DuckType works completely by indentation. If you want to put some paragraphs inside of an item, you just keep them indented. If you want to put a note inside of there, you just indent it further. So if you want to put a note inside of a list item, inside of a list, inside of a table, inside of another note for some incredibly stupid reason, you can actually do that, right? You just keep working with the indentation. Here's a section, same kind of familiar syntax. And here, again, showing that indentation. Here's that item inside of the terms, multiple paragraphs, the example, so we can actually do all of that nesting. But I said that I wanted to do literally everything that Mallard can do. So remember the crazy example that had, you know, all the different extension stuffs, the UI and the ITS and the conditionals and the TTML. Can we do that? And the answer is yes. So this one gets more complicated. We have to declare those namespaces. There's our title. But then we're getting into, here's our conditional processing stuff. Here's the UI thing. There's our media. And there's all of our TTML. Now, is this as pleasant as something that is much more oriented towards, you know, just kind of pages and lists and your kind of core set of block elements? Obviously not. It doesn't look as good as the page we looked at before. But that's just kind of the nature of the material that we're putting in here. It's still more pleasant to read and to write than the XML. I still don't have to put the element name on it again to close everything off, all right? So it's more pleasant than XML at least. And the point is that we can actually do it. So we can take an existing XML vocabulary like TTML or like SVG, and we can still encode it in this compact syntax. And in fact, you can use duct type to write literally any XML syntax you want in a, or any XML vocabulary you want in a non-XML syntax. So I'm going to switch gears again. That was duct type. Now how do you build all of this stuff? I showed you Yelp and Yelp build. Yelp build is a, it's kind of a fire and forget tool, right? You take one document, one version, one translation of one document, you hand it to it, you get some HTML, you can throw that on your web server. But if you're publishing documentation, right, you're publishing a whole documentation site, you probably have multiple documents, multiple versions of documents, multiple translations of documents, you want to have search. So we kind of have all of those tools piecemeal, but it's a lot of work to glue it all together. So the latest tool in this kind of mallard ecosystem is called Pentail. And Pentail is a documentation site generator. It is a static site generator that is geared towards making documentation sites with kind of a mallard first approach to it, but it also supports DocBook and ASCII Doc right now, and it's easy to add other formats. It has a nice plug-in architecture. I'll also mention the Yelp build and Yelp and Yelp check, all of those tools still continue to support DocBook, and so if you're doing DocBook, you should check them out as well because we continue to support DocBook as a documentation format in GNOME. So Pentail, I'll pull up a site. This is Yelp.io, except it's not. It's localhost slash index.html. It's running on my local machine, but it's the same site that's on Yelp.io, except it's got this search box on it that could use a lot of styling work, but I just threw it in there for demo purposes today. And this is the site that kind of gives you some documentation about a lot of the tools that I've been talking about here. So how it's built, let's first look at... There's that front page we were just looking at in DuckType. There's a title, there's that screenshot, a couple of paragraphs, pretty straightforward. And we have a configuration file that tells Pentail how to build it. And this is a short configuration file, but it's actually doing quite a bit. So I tell it, here's some custom XSL that gives me the header and the footer and my CSS and all that stuff. I've got this git plugin that I'm loading in for some reason. And if I go down here, I can provide options on a per directory basis. So in the root directory, I'm saying, copy these extra files. You don't have to specify files that are referenced as images or videos inside your pages. Pentail picks those up automatically. These are kind of in the site white header stuff. So we have to tell Pentail to copy those in. And then these tools and XSL directories, what are these doing? Well, the documentation for Yelp tools, that's Yelp Check, Yelp Build, and a couple of other things, that's actually maintained in the Yelp tools Git repository alongside the code. And similarly, the documentation for the Yelp XSL style sheets is maintained in that repository. I actually document my XSLT shockingly. So we are actually able to tell Pentail that for these directories, I want you to go out to this other Git repository, look in this other directory. We could tell it a branch and get your content from there. And in fact, the stuff that's in the directory right here that we're looking at, the repository we're looking at right here, those are a couple of duct type files. The stuff that's in the Yelp XSL repository, those are actually in XML. So you can mix and match. You can have some of your stuff in duct type, some of it in XML, some of it in doc book or in ASCII doc if you want. Okay. And then one other thing we've got, we've got this stuff about a search provider. So I said the search provider is Elasticsearch. It's running on my machine. And oh my God, there's my username and password. And then down here under XSL, we've got this thing called a search domain. The problem you have with search in a lot of documentation sites, it has no concept of context. If you're on the GNOME developer website and you're on the GTK documentation, if you search for something while you're looking at the GTK API reference, you probably want results from the GTK API reference, not from Glib or Gstreamer or WebKit or something else. You're looking at GTK. Maybe you want to go elsewhere, but that's a good first place to restrict you to. Also, if you have multiple versions of your documentation published, you really don't want to search for button and see the reference for button in the 320 documentation and the 318 documentation and the 316 documentation and probably sort it in a way that doesn't even give you the current first. And this is a problem that you get if you just plug in a generic site search into a documentation site, you just don't get this concept of context. And so the way Pintail deals with this is it allows you to specify a search domain for particular directories. And so you can give it a simple search domain. You can put a directory in multiple search domains. You can put multiple directories into one. You can actually put individual pages into things. But in this case, we're doing something very simple. We're just saying, hey, that XSLT reference, it has its own search domain. Search domain is self. So it has a separate domain from everything else. And I'm going to build this. I'm going to say Pintail build. I'm going to make it verbose. I'm going to say no update. I already have clones of the get repositories it needs to get. And I'm going to have it not try to hit the network and update them because I'm not stupid. And I'm going to go ahead and output directly into the Apache directory. That's not a good deployment strategy, but this is not production. I'm going to throw a couple of balls while this happens. So it's building HTML. These are actually the slash XSL. Those are from the other get repository we told it to go out to. Hey, it takes a little bit of time. So it's building more. Look, it actually found a media file. That's reference. That's that screenshot on the front page. It found that automatically. Here's those other two files we told it that it needed to put in there. And then this is putting the stuff into the index. It's taking all of these pages. It's parsing them. It's looking at what's in them and it's handing them off to Elasticsearch. It made some CSS and JavaScript. So I'll go into the XSLT. Look at the parameters. mel.f.custom if you want to override the conditional processing. That's the parameter you want. And I'm going to search for TTML because we talked about that. And I get some results. And again, I'm getting search results on a statically generated site. And these here, because I'm in the XSLT reference, here are parameters, style sheets, templates that support TTML that allow TTML to work in all of these tools. So if you're hacking on the style sheets or trying to extend them, this is probably what you want. But if you're not, right, my search results right now are restricted to the API reference for the Yelp XSLT style sheets. If you're just looking for information on how to use TTML, that's not what you want. So go ahead and we'll change the search domain and we'll go look at the entire site instead. Our search results change. And here the very first hit is a page that gives you some information on how to use TTML inside of Mallard with all of the Yelp tools. So, Mallard, YelpCheck, YelpBuild, Yelp, ITSTool, DuckType, Pintail, and I am, wow, I did better on time than I expected. That was everything I was going to show. If you want more information on any of this stuff, I have literally been throwing the URL at you for the last 20 minutes. And that's all I've got. I think we have time for one short question. If anyone's got one, we can take it outside. Is there any sort of validation for DuckType or does it validate if there is any sort of validation for DuckType or does it validate by... So the approach that I've taken with DuckType is mostly take advantage of all of the tooling that we have around XML. And so if you want to do validation in the way that an XML person would talk about it, which I think you and I are there, then you're going to push it out to the XML and you're going to validate against the relax-and-gee schemas. Now, there are, you know, syntax checking, there is that, but making sure that you have the right kind of document structure, I would go out to the XML. And the same is my approach for translations. We already have an extremely powerful XML translation tool. And so the translation strategy is put the stuff to XML first and then do your translations there. That could change in the future, but because there's such a wealth of XML tools, it's nice to build on those. Any other questions? We'll take them outside because we've got to set up for the last four. Thank you. And I have a bag of balls. Thank you.