Home Connect Gallery Blog

Humphrey School Pachyderm Manual (PachyMan)



Hi there!

My name is Jade Thornton. While I did not create the new employee orientation Pachyderm presentations, I have done some extensive editing and maintenance. The majority of changes I made use hypertext markup language (HTML), so I created this manual as a reference for anyone who might be maintaining what I've written. This manual is generally true for all HTML, but I've simplified some details which aren't relevant to working with the Humphrey School instance of Pachyderm.

If you are already comfortable with HTML, you need not read past this insert

Pachyderm is atypical in that it renders all whitespace written. This means every line break (pressing enter or return) used to make code readable is translated as a <br>. To get around this, explicitly specify your line breaks, then minify your code.

Get ready

All HTML is stored as a regular old text file, except that the file extension is ".html" and whatever software is reading it is told it's HTML. Because of this, absolutely any text editor will work just fine for editing what I've written. I do recommend using a text editor rather than just using the text box in Pachyderm, however, for one good reason: syntax highlighting. This means that different HTML elements will have different colors so you can very quickly tell the difference between a tag, some text, a URL, etc.

For all users (Windows and UNIX), I cannot recommend more highly the free and open-source text editor Atom. It's what I'm using to write this right now, and there is nothing that can beat it. On the other hand, others may disagree on the awesomeness of Atom. If you're one of those people, check out Eclipse, Sublime or Kate.

Intro

This is not going to be a class on HTML. I'm not going to give you a whole lot of "why", mostly "what" and "how to use". There are fantastic resources online for further learning if you're interested, namely lynda.com (free for University employees, go to lynda.umn.edu) and freecodecamp.com.

Basics

First off, you need to know what I mean when I say "tag". That basically means anything inside <>, angle brackets. These are what tell Pachyderm what you want to do with the text following the tag (make it bold, make it a link, turn it into a list, etc.). Almost every tag in HTML must be followed by a closing tag, which will look something like </>. This tells Pachyderm where the end of that tag is. Look for this in the examples below.

Secondly, you need to know the right order in which to close tags. This means the last tag you open is the first tag you close. If we have an imaginary tag called <foo> and another one called <bar>, I can use them both on the same text at the same time, but I have to close them in the right order:

<foo><bar>Some very special foobar text</bar></foo>

Notice that I opened the <foo> tag first, so I close it with </foo> last. <bar> is on the inside of <foo> so it has to be closed with </bar> before I close <foo>. Keeping track of this ordering might be somewhat tedious when you're not used to it, but it's very important to do.

Thirdly, Pachyderm text boxes have a maximum size of 1500 characters. One way to help keep under this limit is to shorten all your links. I like to use Bitly for page links and Slimg for images.

Finally, you need to understand how I've structured this manual. Each entry is about a single tag. They are in alphabetical order and separated by horizontal lines. The heading shows what the tag looks like, and the name and explanation follow. Under that, there is a code block, which contains an example of how to use the tag. Beneath the block is what the code in the code block renders to. When I say render, I mean the text that Pachyderm (or a web browser) would show if you put in the code.

If you find a bug, error, want to make a change or have any questions, take a gander at the help page. You can visit this page any time by using the "Help" button at the top of the screen.


<a>

Anchor -- This tag is used to create a link to another web page. Whenever you see a blue underlined link online, you know it's because of an anchor tag! The href attribute contains the URL the link will point to. Note: The link must be contained within quotes. They can be single quotes (') or double quotes (") as long as both sides of the link have the same kind of quotes.

    <a href="https://jmthornton.net">I'm a link!</a>

I'm a link!


<br>, also <br />

Line Break -- This handy little tag is extremely convenient when working with Pachyderm. It inserts a line break wherever you want it. It has the same effect as pressing enter in a text editor (like Atom or Eclipse) or word processor (like Word or Writer). See the minimization section for an explanation of why this tag is so important in Pachyderm. Note: the line break tag is an exception to the rule of needing a closing tag -- it's "self-closing". This means you only need one tag to get the job done.

Go placidly amid the noise and haste,<br>and remember what peace there may be in silence.

Go placidly amid the noise and haste,
and remember what peace there may be in silence.


<dd>

Description Definition -- This is used together with <dl> and <dt> to create an entry kind of like a dictionary. The description definition comes after the <dt> description term.

<dl>
    <dt>Jade Thornton</dt>
    <dd>The best developer ever</dd>
    <dt>Humphrey School</dt>
    <dd>The best policy school ever</dd>
</dl>
Jade Thornton
The best developer ever
Humphrey School
The best policy school ever

<div>

Division -- This is perhaps the most common tag used in full-blown HTML, though I've used it sparingly in Pachyderm. Not to be confused with mathematical division, this tag separates HTML into sections. A class or id attribute identifies the division so Pachyderm can find it by its name.

<div class="fun" id="the-best-div">I don't look like much, but I'm text inside a div</div>
I don't look like much, but I'm text inside a div

<dl>

Description List -- This is used together with <dd> and <dt> to create an entry kind of like a dictionary. The description list encloses the list elements, <dd> and <dt>. This list is not numbered nor bulleted.

<dl>
    <dt>Jade Thornton</dt>
    <dd>The best developer ever</dd>
    <dt>Humphrey School</dt>
    <dd>The best policy school ever</dd>
</dl>
Jade Thornton
The best developer ever
Humphrey School
The best policy school ever

<dt>

Description Term -- This is used together with <dl> and <dd> to create an entry kind of like a dictionary. The description term acts like the word which is being defined by <dd>.

<dl>
    <dt>Jade Thornton</dt>
    <dd>The best developer ever</dd>
    <dt>Humphrey School</dt>
    <dd>The best policy school ever</dd>
</dl>
Jade Thornton
The best developer ever
Humphrey School
The best policy school ever

<em>

Emphasis -- Emphasizing something in HTML means to make it italicized. Yes, there is an <i> tag, but we don't use it. Learn why.

<em>I am some very stylish italicized text</em>

I am some very stylish italicized text


<hr>

Horizontal Rule -- This tag inserts a horizontal line, exactly like what you see separating tag explanations here. Note: This is an exception to the rule of needing a closing tag -- it's "self-closing". This means you only need one tag to get the job done.

I am some really nice text, but I want some privacy from my nosy neighbor.
<hr>
Don't listen to that text, I'm not nosy!
I am some really nice text, but I want some privacy from my nosy neighbor.
Don't listen to that text, I'm not nosy!


I've changed the rendered example a little bit so the <hr> isn't confused with the lines I'm using between tag explanations. The box would not normally show up.


<img>

Image -- Exactly what it says on the tin, this tag puts an image in right where you put the tag. Put the url for the image into the "src" attribute. Remember to put in alternate text in the "alt" attribute. This is done to make the presentation more accessible to those who use screen readers.

<img src="https://jmthornton.net/assets/images/Placeholder.jpg" alt="A beautiful placeholder image">
A beautiful placeholder image


I've changed the rendered example a little bit so it's a manageable size


<li>

List Item -- This is part of creating a list (with bullet points or numbers). A <li> tag surrounds each item in the list. In the example below, a bulleted list is used to show items I happen to need to get from the store this weekend. When this is rendered in Pachyderm, each item in a <li> tag will have its own bullet point.

<ul>
    <li>Milk</li>
    <li>Carrots</li>
    <li>Sweet potatoes</li>
</ul>
  • Milk
  • Carrots
  • Sweet potatoes

<ol>

Ordered List -- This tag encloses list items (<li>'s) and creates a numbered list.

<ol>
    <li>Buy low</li>
    <li>Sell high</li>
    <li>Profit</li>
</ol>
  1. Buy low
  2. Sell high
  3. Profit

<p>

Paragraph -- While simply writing out text in Pachyderm works just fine, using <p> is sometimes a nice way to separate the text from other nearby parts. In Pachyderm, this does not change the formatting of the text.

<p>How now brown cow?</p>

How now brown cow?


<strong>

Strong -- Use this tag to make text bold. Yes, there is a <b> tag, but we don't use it. Learn why.

<strong>Bold text</strong>

Bold text


<ul>

Unordered List -- This tag encloses list items (<li>'s) and creates a bulleted list.

<ul>
    <li>Capybaras are better than dogs</li>
    <li>Dogs are better than most animals</li>
    <li>Bunnies are better than every animal ever</li>
</ul>
  • Capybaras are better than dogs
  • Dogs are better than most animals
  • Bunnies are better than every animal ever

<!-- -->

Comment -- This is actually two tags, <!-- and -->. Any text put between these tags is a comment, and Pachyderm won't render it at all. These are used to make notes for yourself or others. Note: Though the user can't see comments, they still count towards the 1500 character limit.

<!-- I'm a happy little comment which likes to hide! -->


No, I didn't forget to put the code under the code block. It's a comment so it doesn't show up! Take a look at the source code to see that there really is a comment there (hint: check line 459).


Style

The primary reason I edited these Pachyderm presentations was to improve their style. Let's talk about some of the big style decisions I made, which are decisions I think you, as an editor of these presentations, should stick to and be sure to standardize across the board.

  • There are no descriptions on pictures. Previously, the descriptions simply instructed viewers to click on the image, which was a link to an external resource. This is a far outdated design practice, which has been abandoned in favor of intuitive controls. The images still link to external resources, as do the little globe icons next to them, but to make the experience more intuitive:

  • I added "Learn more" links to most pages. They link to the same external resource as the images, but require no instructions for a user to know what to do. If a user wants to learn more, they click the link that says "learn more".

  • I only used images licensed under a Creative Commons license. Knowledge is free, and open-source is the future. Creative Commons images allow me to make changes I want and to use them in any way I want. I highly encourage you to only use images which are also copylefted.

If you've already explored the presentations, which you probably have, you'll notice something about what I just said. They're not entirely true. There is at least one exception to every bullet I listed above. I'm a pragmatic man, and I made design decisions based on specific situations. You, as the editor and/or maintainer of the presentation have the full power to make your own design decisions. I only ask that you adhere to the following design rule:

Don't make the user think. Make features and options obvious; if you have to explain something to the user, it means you need to rethink it yourself (which makes this manual a bit hypocritical, huh?). We want the user to enjoy using these presentations, and that means they shouldn't notice most of it; it should be automatic.


Minimization (aka Uglification)

Now here's an important piece of advice I figured out the hard way. Pachyderm renders HTML differently from the way a normal browser would: it renders all whitespace. This means every time you press enter, Pachyderm treats it like you wrote <br>. To get around the very annoying spacing problems this can cause, your HTML code needs to be minimized. This essentially means that all the whitespace will be removed, and the entire section of HTML code will be put onto a single line. Here's what you need to do to minify your code for Pachyderm:

  1. Have your HTML you want to minify open in a text editor of some sort
  2. Go to www.willpeavy.com/minifier
  3. Copy and paste your code into the text box on the website
  4. Click the "Minify" button
  5. Copy and paste the minified code into Pachyderm
  6. Make sure to preview the screen to verify it looks like what you wanted

Beautification (aka the opposite of minification)

This might be an important step in decoding what I've put up on Pachyderm, and for maintaining the presentations in general. If you're using the Atom editor (the best one), install the atom-beautify package. If you're on some other editor, or don't like Atom packages, I recommend the following steps.

  1. Have the HTML you want to beautify open in Pachyderm
  2. Go to ctrlq.org/beautifier
  3. Copy and paste your code into the text box on the website
  4. Click the "Beautify Code" button
  5. Copy and paste the minified code into your text editor

An example Pachyderm text entry

Let's run through an example of putting together tags to create a pretty text entry in Pachyderm. This code is taken from the "Research" slide of the "Our School" screen as it appeared in September 2016.

When we open up the slider in Pachyderm, this is the code we find in the text box:

<strong>Research centers and projects by policy area:<br /></strong><dl><dt>Global Policy</dt><dd><a href="https://bit.ly/2cgGidU">Freeman Center for International Economic Policy</a></dd><dd><a href="https://bit.ly/2cfov9s">International Fellows and Scholars</a></dd><br /><dt>Leadership and Management</dt><dd><a href="https://bit.ly/2cL0CZ0">Center for Integrative Leadership</a></dd><dd><a href="https://bit.ly/2cLtRMy">Public and Nonprofit Leadership Center</a></dd><br /><dt>Politics and Governance</dt><dd><a href="https://bit.ly/2cgGPMX">Center for the Study of Politics and Governance</a></dd><br /><dt>Science, Technology and the Environment</dt><dd><a href="https://bit.ly/2cfnttY">Center for Science, Technology, and Environmental Policy</a></dd><br /><dt>Social Policy and Policy Analysis</dt><dd><a href="https://bit.ly/2ccUlkZ">Center on Women, Gender and Public Policy</a></dd><dd><a href="https://bit.ly/2cjzyiQ">Human Capital Research Collaborative</a></dd><dd><a href="https://bit.ly/2czQj6S">Roy Wilkins Center for Human Relations and Social Justice</a></dd><br /><dt>Urban and Regional Planning</dt><dd><a href="https://bit.ly/2cfoMsQ">State and Local Policy Program</a></dd></dl><br /><br /><br /><a href="https://www.hhh.umn.edu/people-research/research-centers">Learn more</a>

Looks messy, right? That's a breeze for a computer to read, but we're not computers! Let's beautify it so we can read it. I'm going to use the Atom package atom-beautify for this one. Here's what I get:

<strong>Research centers and projects by policy area:<br /></strong>
<dl><dt>Global Policy</dt>
    <dd><a href="https://bit.ly/2cgGidU">Freeman Center for International Economic Policy</a></dd>
    <dd><a href="https://bit.ly/2cfov9s">International Fellows and Scholars</a></dd><br /><dt>Leadership and Management</dt>
    <dd><a href="https://bit.ly/2cL0CZ0">Center for Integrative Leadership</a></dd>
    <dd><a href="https://bit.ly/2cLtRMy">Public and Nonprofit Leadership Center</a></dd><br /><dt>Politics and Governance</dt>
    <dd><a href="https://bit.ly/2cgGPMX">Center for the Study of Politics and Governance</a></dd><br /><dt>Science, Technology and the Environment</dt>
    <dd><a href="https://bit.ly/2cfnttY">Center for Science, Technology, and Environmental Policy</a></dd><br /><dt>Social Policy and Policy Analysis</dt>
    <dd><a href="https://bit.ly/2ccUlkZ">Center on Women, Gender and Public Policy</a></dd>
    <dd><a href="https://bit.ly/2cjzyiQ">Human Capital Research Collaborative</a></dd>
    <dd><a href="https://bit.ly/2czQj6S">Roy Wilkins Center for Human Relations and Social Justice</a></dd><br /><dt>Urban and Regional Planning</dt>
    <dd><a href="https://bit.ly/2cfoMsQ">State and Local Policy Program</a></dd>
</dl><br /><br /><br /><a href="https://www.hhh.umn.edu/people-research/research-centers">Learn more</a>

That's a little better. For the purposes of explaining, I'm going to beautify it a little more by hand. I'm also going to cut out some of the links in the middle to make it shorter (this is only an example after all).

1  <strong>Research centers and projects by policy area:<br /></strong>
2  <dl>
3      <dt>Global Policy</dt>
4      <dd>
5          <a href="https://bit.ly/2cgGidU">Freeman Center for International Economic Policy</a>
6      </dd>
7      <dd>
8          <a href="https://bit.ly/2cfov9s">International Fellows and Scholars</a>
9      </dd>
10     <dt>Urban and Regional Planning</dt>
11     <dd>
12         <a href="https://bit.ly/2cfoMsQ">State and Local Policy Program</a>
13     </dd>
14 </dl>
15 <br /><br /><br />
16 <a href="https://www.hhh.umn.edu/people-research/research-centers">Learn more</a>

Much better. I've also added line numbers so we can easily refer back to this code block. Now let's go through it line by line together.


1  <strong>Research centers and projects by policy area:<br /></strong>

Here we open with a <strong> tag. Recall that this turns the following line of text bold. At the end, we see a <br /> which causes a line break after this text (<br> and <br /> are equivalent). At the very end, we close the strong tag.


2  <dl>

We are going to begin a description list, so we open the list using <dl>.


3      <dt>Global Policy</dt>

Here's the first description term in our list, which we enclose in opening and closing <dt> tags.


4      <dd>

Our description term needs a definition, which we begin with an opening <dd> tag.


5          <a href="https://bit.ly/2cgGidU">Freeman Center for International Economic Policy</a>

Here's our description definition, which happens to be a link. Links are created using the anchor tag. Inside of the opening anchor tag, we add an attribute called href, which has a value of "https://bit.ly/2cgGidU". Remember to put the link in quotes. This link is shortened using Bitly to conserve characters (recall that Pachyderm has a character limit of 1500). At the end of the line, we remember to close the anchor.


6      </dd>

That's the end of our definition, so we close it with </dd>


7      <dd>
8          <a href="https://bit.ly/2cfov9s">International Fellows and Scholars</a>
9      </dd>

These lines are built the same as lines 4-6.


10     <dt>Urban and Regional Planning</dt>

Now we want to define another term, so we open it with a description term tag, with a closing tag at the end of the line.


11     <dd>
12         <a href="https://bit.ly/2cfoMsQ">State and Local Policy Program</a>
13     </dd>
                                        

These lines are built the same as lines 4-6.


14 </dl>

That's the end of the description list! Don't forget to close it with </dl>


15 <br /><br /><br />

Here we have some more line breaks. On every page which includes a "Learn more" link, I put three line breaks between it and the rest of the content. I typically put two line breaks between paragraphs.


16 <a href="https://www.hhh.umn.edu/people-research/research-centers">Learn more</a>

Speak of the devil, here's our "Learn more" link! Every one of these bad boys links to the same place the picture links to. Read about the reasoning for this in the style section of this manual.


There we have it! That's one of the most HTML-rich slides in the whole presentation. Some slides don't even have any HTML at all! Let's take a look at the code we just talked about:

Research centers and projects by policy area:

Global Policy
Freeman Center for International Economic Policy
International Fellows and Scholars
Urban and Regional Planning
State and Local Policy Program




Learn more

Not too shabby!


Conclusion

Hooray!! That's it! You should be good to go to figure out everything I've written in Pachyderm and make any changes you'd like. If you're feeling adventurous, there are dozens more HTML tags to explore; Pachyderm will render most anything under the HTML5 specification. If you get stuck or don't know what to do, internalize the mantra "Read, Search, Ask". This means:

  1. Read the description of what you're trying to do (RTFM). This could mean looking at this manual again or going online to the HTML5 documentation (go to w3.org or the Mozilla Developer Network)
  2. Search online to see if anyone has had the same problem (they probably have). Stack Overflow is by far the best place to look for this sort of thing
  3. Ask someone who knows or talk to Humphrey IT. We'd all love to help you out.