Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine
 
PerlMonks  

TOC draft sample

by ww (Archbishop)
on Nov 07, 2017 at 13:14 UTC ( #1202922=monkdiscuss: print w/replies, xml ) Need Help??

Draft, sample revision of Markup in the Monastery per LanX's excellent suggestion that we include TOC's in at least some informational nodes. Thanks LanX!
Comments, please, from all (and see Re: TOCs and deeplinks for our house rules for background/my comments).

Update/edit: per suggestions in replies from LanX and pryrt, some chapter titles in the body of the doc have been changed to more closely match the TOC entries.

Markup in the Monastery

Contents:

Chapter 1 - Basics: Para & Code markup

There are just two basic markup elements you MUST use when posting a comment or question:

<p>...</p> Paragraph tags, so the narrative part of your node won't be an unreadable mismash.

...and

<c>...</c> Code tags around code and data (which can be cut and pasted direct from your editor).

And now you know those, you can go back to creating your node unless you'd like to learn more.

Chapter 2 Additional Markup (Overview+Examples)

Here's a synopsis of important tags and their actions:

Your PostPM Markup:Result:
Paragraphs
<p>first paragraph</p>
<p>second paragraph</p>

first paragraph

second paragraph

Code
<p>The result is in <c>$array[0]</c></p>

The result is in $array[0]

<c>
use strict;
use warnings;

my @array = ("Hello world\n");
if (@ARGV) {
    print $array[0];
}
</c>
use strict; use warnings; my @array = ("Hello world\n";); if (@ARGV) { print $array[0]; } #
Note: The "download" link is automatically displayed on <c>...</c> blocks. It links to a raw display of the displayed code. You don't need to do anything to enable this link.
link to PM nodes by name

Have you tried [Super Search]?
Have you tried Super Search?
Thanks for your help, [tye]
Thanks for your help, tye
Thanks for nothing, [tye|wiseguy]
Thanks for nothing, wiseguy
Link to PM nodes by ID
Please consult [id://3989]
Please consult Super Search
External Links
Did you try [http://www.activestate.com/]?
Did you try http://www.activestate.com/?
Other kinds of links
(more info)
Check out [pad://NodeReaper]
Check out NodeReaper's scratchpad
Did you check [doc://perlfaq]?
Did you check perlfaq?
text/font formatting
This will be <b>bold</b>
This will be bold
This will be <i>italic</i>
This will be italic
This will be <tt>fixed width</tt>
This will be fixed width
Blockquotes (indented)
A wise monk once said:
<blockquote>
"Indenting is good"
</blockquote>
.. and I agree
A wise monk once said:
"Indenting is good"
.. and I agree
Lists
My favorite flavors are:
<ul>
<li>vanilla</li>
<li>chocolate</li>
</ul>
My favorite flavors are:
  • vanilla
  • chocolate
How to make toast:
<ol>
<li>insert bread</li>
<li>press button</li>
</ol>
How to make toast:
  1. insert bread
  2. press button

Chapter 3 - Warnings & Tips

PM markup code is NOT entirely w3c html 4.01 standard nor is it XHTML, so even if you're expert please scan these notes.

Textual content:

Ordinary paragraphing is accomplished with <p>...</p> tags, which (imprecisely) allow you to have your text appear in what may be called "conventional" paragraphs; that is with blank lines between paragraphs. That's highly recommended, as it makes your node easier to read.

Links: Please, do NOT use <a href="http://example.com">something</a>. Instead, create links (especially those to nodes at PM) using [...] The ... inside the square brackets may be a node's title or its id://(number). Optionally, you can override the target's title with your chosen alternate by adding |(some word or phrase) after the id or title before closing the square brackets.

For example, [Super Search|Did you try to find that here?] will render as Did you try to find that here?. More extensive and sophisticated information can be found in What shortcuts can I use for linking to other information?.

Lists: lists can be either ordered (decimal numbered - using Roman numerals or letters is beyond the scope of this note) or unordered (bulleted). One of each follows; first the ordered list, created with this:

<ol><li>line 1 of list</li><li>line 2 of list</li><li>and so on</li><ol>

  1. line 1 of list
  2. line 2 of list
  3. and so on

The unordered list uses <ul>...</ul> around the list item <li>...</li> tags:

  • line 1 of list
  • line 2 of list
  • and so on

<b>...</b> can be used to enclose words, phrases or sentences you want to have appear in boldface. As a courtesy, do NOT abuse this... and use the preview function to check. Similarly, <i>...</i> can be used to italicize content.

<tt>...</tt> tags surrounding a word or phrase (commonly, a single key word or symbol) cause that word or phrase to be rendered in something akin to a system font; eg: key words within the surrounding text.

Heading tags, <h3>...</h3>, and smaller (through <h6>) may be used. Head tags, unsurprisingly, cause their content to render as headlines. For example

<h4>A headline<h4>

<h6>A smaller headline</h6>

Any <hn> ... </hn> tag pair can be thought of as implying line breaks above and below (absent manipulation with css or other techniques far beyond the scope of this node). Please note that <h1> and <h2>are discouraged here.

<blockquote>...<blockquote> is used to indent a (brief, please) segment of your text and works like this (the fixed width pseudo-tags, below, illustrate the actual useage):

<blockquote>This is a blockquote. Note that it is indented both left and right and offset top and bottom by a blank line. This blockquote rambles on to ensure that regardless of the width of the viewer's browser window, there are multiple lines inside the blockquote. Note that there are no paragraph tags around this paragraph although using them would be allowed...and that it is permissible to include, for example, <b>textual</b> <i>markup
</i><c> inside the blockquote. <p><c><p>
What's more a blockquote can include multiple paragraphs. Again, this is padded with enough non-substantive verbiage to make it wrap in most user's browser windows.</p></blockquote>

If you find it necessary (and you should make every effort to ensure it is NOT) to create a very long post, please use <readmore> ... </readmore tags. Should your post make it to the front page, the readmore segment collapses to a link by which the interested reader can see the entire post.

Puzzle answers aka spoilers

If you post a puzzle, enclose the answer in <spoiler></spoiler> tags, so you don't spoil the puzzle fun for others.

Detail: <spoiler>...</spoiler> tags are intended to (temporarily) redact (in the intel world's sense; "black out") some brief piece of text or code whose visibility would spoil a thread for some future reader. Example:

In a simple case, the material inside the spoiler tags will become visible when highlighted; the general idea being that a little more work is required to see the content than simply viewing a node.
The reader's preference settings may cause <spoiler> tags to be rendered in unexpected ways.  Note that when wrapped in <c><code> tags the </c></c> tags will be treated as literal text.

Nesting: Check for proper nesting. For example, if you open a paragraph tag, close it before beginning a blockquote or code segment. And that leads us directly to the next important pair of tags.

Code:

Use code tags, <c>..</c> (or <code>...</code>), to post code and data. Doing so preserves your indentation, blank lines and those symbols for which use of character-entities is conventional elsewhere. Char-entities are discussed further, below

A typical use would be to cut'n'paste your code into a PM node Code tags cause the code (or data) they enclose to appear in a distinguishable font. If you have turned on line-numbering in the section on "Code Listing Setings" in Display Settings the code lines will be numbered. The following is inside <c>...</c> tags.

#!/usr/bin/perl use warnings; use strict; use (some module); if (some condition) { do something; and something more; # with a comment to make this a very, very lon +g line which will wrap in many browser windows, absent a gigundo moni +tor and so on. If you don't have auto code wrap on in "code," you'll +see a red plus sign and a lack of line number on the continuations af +ter wrapping is performed (sometimes at unfortunate points, as can be + seen in this instance, if you don't have auto code wrap turned on. } else { &whatever; # Note below } sub whatever { do something; }

Note the download link, above. It appears after each stand-alone code block and allows readers to retrieve the code or data, without the line numbers.

Note that in line 11 the "&" did NOT have to be written as a character entity (&amp;). If you're not seeing line numbering, see that setting in Display Settings.

<pre> vs. <code>

At first blush, the <pre> ...</pre> pair may look like an alternative to code tags... BUT DON'T USE IT HERE chiefly because <pre>...</pre> tags will not persuade the Monastery to provide a download link for the contents of the <pre>... and while it is now supposed to wrap lines that are too long for the viewer's browser window, there are ways Monks could use CSS that would defeat that. So, please. don't use <pre>...</pre> except to deal with exceptional cases... like that in the next paragraph (which still needs examples of using pre inside a long stretch of code).

Exception: non-ASCII characters inside the ... may magically display as unrendered entities (i.e., as question-marks) instead of the character you expected, whereas inside <pre> ...</pre>, they may work as expected. (Thanks, pryrt).

More untoward or problematic markup

Inserting a <br> tag forces a newline at the point at which it's inserted. Monastery documents differ on its acceptability but in the form in this sentence, it generally works... while alternates, like XHTML's <br /> do NOT work.

Using <div>...</div> tags is NOT deprecated, but unless you're expert in .html, you probably shouldn't use them here.

<font (something="something")>... </font> tags are frowned upon. Don't use them except in extraordinary circumstances.

Character Entities

Please read carefully the hints which appear below the text entry box when you're creating a node. Outside code tags

For: Use:
&  &amp;
<  &lt;
>  &gt;
[  &#91;
]  &#93;
 &trade;
®  &reg;
©  &copy;
 &mdash;

Appendix

If you are a logged-in user, you have Display Settings which you can check or change. See particularly the section HTML Related Options. It is highly recommended that you check the checkbox and set the two other options to their maximum values (3 and 4, respectively). These will tell you quite clearly when you omit a required tag, and will help when you bork tag nesting rules.

Most of the tags discussed above should be used in pairs (that is, <tag>... </tag>. While some of the other tags addressed in this node will DWIM even if you fail to close them, the <b>, <i>, and <tt> tags will not, nor will some "block level" tags like <ol>.

A table listing all PM-approved html and arguments is available for those who wish to delve deeper.

Beware of using your browser's "view page source" feature to see how a writeup has been formatted. Not only are you viewing a node after it has been processed by PerlMonks (turning What shortcuts can I use for linking to other information? into actual links, for example), but many browsers do additional processing on received pages, such as inserting missing closing tags.

In the interest of brevity and simplicity, some statements above are oversimplified... and some do NOT apply to the CB, for which see PerlMonks Approved Chatter HTML Tags.

...and finally

None of this will be much help if your content is unclear. Use an explanatory title, standard spelling, grammar, and punctuation. If posting a question, explain exactly what your problem is (and include warnings and error messages, verbatim, if received). Tell us what your input is in a separate code block or as a <DATA> section at the end of your code. Be explicit about the expected output, unless that's utterly unambiguous, and tell us how what you're getting, if anything, deviates from your expectations or desires.

How do I post a question effectively?, Before You Post ... and On asking for help address many valuable points. If you're new to the Monastery, you'll profit greatly — EVEN IF YOU'RE IN A RUSH TO GET AN ANSWER — by reading these. And, oh yes, remember, "Your 'urgent need' is not our emergency."


Back to the PerlMonks FAQ.

As noted above, please comment here or address comments to ww.

Replies are listed 'Best First'.
Re: TOC draft sample
by LanX (Bishop) on Nov 07, 2017 at 17:30 UTC
    1. I'm not sure why you have different headings and TOC entries

    why not simply

    <h3>Chapter 1 - Basics: Para &amp; Code markup</h3> for both?

    2. Your anchors are manually designed too, while those generated by my script should be safe.

    Whats the issue? Length?

    The benefit of long anchors is that they could later be easily expanded to text again.

    3. IMHO you should convert sub-headings to <h4> to get proper nesting. (like this )

    4. Your example headings like <h6> can be excluded by either

    • indenting them (only at start of line is parsed to TOC ) or
    • entering a linebreaks in the middle (only lines are parsed for h-tags)*

    5. See also the way I'm back-linking to the TOC here: Re^2: TOCs and deeplinks for our house rules to facilitate navigation

    6. Also switching <ul> to <dl> is an option, if needed.≤

    I can adapt my script to different needs if the monastery comes to a consensus.

    Long time goal could hopefully be to add something like <toc> to our markup toolset to simplify the process.

    Cheers Rolf
    (addicted to the Perl Programming Language and ☆☆☆☆ :)
    Je suis Charlie!

    *) this has multiple advantages.

    ≤) IMHO depends on desired CSS features

Re: TOC draft sample
by pryrt (Curate) on Nov 07, 2017 at 14:25 UTC

    were the contents of the first three <h3>'s originally "Chapter 1", "Chapter 2", and "Chapter 3"? When I went to check the original, they appear to be "chapter #" now... but I didn't remember that it was such blandly-titled sections before, and the TOC names listed here (with "Basics: Para & Code markup" and other similarly-helpful titles) make more sense. Did the auto-generation of the TOC somehow mess up the source?

      By me, no changes of the sort you're asking about since I posted the original node
      and not sure what you're seeing. Also, no auto-generation of the TOC used -- about which, see my linked response -- as edited upon posting of the "Draft...." -- to the original LanX suggestion.

        In the table of contents, the entries are listed as "Basics: Para & Code markup", "Additional Markup (Overview+Examples)", and the like. In the body of the document, those same are "<h3>Chapter 1</h3>" and "<h3>Chapter 2</h3>". As LanX put it, " why not simply <h3>Chapter 1 - Basics: Para & Code markup</h3> for both?".

        It had been a while since I'd read the original Markup in the Monastery node, and I had assumed that something had been changed, because I didn't remember those sections being called "Chapter 1" and "Chapter 2" in the original... but apparently I was wrong. Sorry.

        I guess now my suggestion (to echo LanX), would be to use the same meaningful names that you manually chose for the TOC as the actual headers in the flow of the document. (Clicking on "Basics: Para & Code markup" and arriving at "Chapter 1" is confusing to me, and would likely confuse someone new to the document as well.)

Re: TOC draft sample
by pryrt (Curate) on Nov 09, 2017 at 14:36 UTC

    Not related to the TOC, but while we're talking about editing this page anyway... Do we really still want to recommend never using <PRE>? Because, as per Re: Non asci character and system call and its followup, and has been seen elsewhere (for example, here), if you want to include non-ASCII in your code snippet, you need to use <PRE>. So, possibly something like:


    CODE vs PRE

    At first blush, the <pre> ...</pre> pair may look like an alternative to code tags... BUT DON'T USE IT HERE chiefly because <pre> ...</pre> tags will not persuade the Monastery to provide a download link for the contents of the <pre>... and while it is now supposed to wrap lines that are too long for the viewer's browser window, there are ways Monks could use CSS that would defeat that. So, please, don't use <pre> ...</pre>.

    Exception: non-ASCII characters inside the <code>...</code> may magically display as unrendered entities instead of the character you expected, whereas inside <pre> ...</pre>, they work as expected. For example,

    <code>
    $checkmarks="☐☑☒✓✗";
    ...
    </code>

    will render as

    $checkmarks="&#9744;&#9745;&#9746;&#10003;&#10007;"; ...

    whereas

    <pre>
    $checkmarks="☐☑☒✓✗";
    ...
    </pre>

    will render as

    $checkmarks="☐☑☒✓✗";
    ...
    

    Other Tags You Should NOT Use


    update 1: renamed the section and fixed paragraphing, plus made the CODE multiline, so it properly renders with the download-link

    update 2: clarified the text to explicitly say that PRE should be used in the case of non-ASCII

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://1202922]
Approved by Corion
Front-paged by Athanasius
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (5)
As of 2017-12-16 14:14 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What programming language do you hate the most?




















    Results (453 votes). Check out past polls.

    Notices?