http://qs321.pair.com?node_id=852471

UPDATE: Plz see Re^4: using <pre> tags for citing perldocs! (Solution with personal "Display Settings") !

Hi

using <pre> tags are considered a sin within the monastery, but I wanna suggest to use them when citing from perldocs and similar sources.

When displayed in a terminalš the docs already have a hard linebreak only some characters longer than <code> has, always inserting "+" breakes for these <10 chars IMHO doesn't worth it.

Please compare the readability of

using <code>

        The auto-increment operator has a little extra builtin magic t
+o it.
 
...
       "undef" is always treated as numeric, and in particular is chan
+ged to 0
       before incrementing (so that a post-increment of an undef value
+ will
       return 0 rather than "undef").

[download]

using <pre>

        The auto-increment operator has a little extra builtin magic to it.
 
...
       "undef" is always treated as numeric, and in particular is changed to 0
       before incrementing (so that a post-increment of an undef value will
       return 0 rather than "undef").

if someone is concerend about font-size you might add additional <tt>

using <pre><tt>


        The auto-increment operator has a little extra builtin magic to it.
 
...
       "undef" is always treated as numeric, and in particular is changed to 0
       before incrementing (so that a post-increment of an undef value will
       return 0 rather than "undef").

Another possibility could be to augment the chars/line number in <code> to allow easy citing of perldocs.

Cheers Rolf

1) hmm depends on the terminal-with but perldoc seem to have a min-width of 80 chars.

UPDATE: Hmm ... the line-width of perldocs seems to be a convention, it depends on the author if he wraps after 80 chars.

The synopsis of Scalar::Util is an example for bad formatting.

Replies are listed 'Best First'.
Re: using <pre> tags for citing perldocs!
by toolic (Bishop) on Aug 02, 2010 at 14:09 UTC
    When I quote from the docs, I use <blockquote>:
    The auto-increment operator has a little extra builtin magic to it. If you increment a variable that is numeric, or that has ever been used in a numeric context, you get a normal increment. If, however, the variable has been used in only string contexts since it was set, and has a value that is not the empty string and matches the pattern /^[a-zA-Z]*[0-9]*\z/ , the increment is done as a string, preserving each character within its range, with carry:

    It autoscales the width nicely.

[reply]
[d/l]
[select]
      good point ... but paragraphs and newlines get lost.

      123456789 123456789 123456789 123456789 123456789 123456789 123456789 
+123456789

      [download]

      code tags in the monastery seem to break after 70 chars, simply extending them to 80 chars would solve the problem in most cases, since xterms default to 80x25.

      I think nowadays thats acceptable, another - backward compatible - solution would be a new tag "quote" which works like "code" but with 80 chars wrap.

      <quote> 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789
      </quote>

      Cheers Rolf

[reply]
[d/l]
        <blockquote>

        <p>I suppose they<br />
        might…</p>

        <p>If you don't know how teh Intertubes work.</p>

        </blockquote>

        (I know, I know, it's not as DWIW but it's still always there.)

[reply]
[d/l]
[select]
Re: using <pre> tags for citing perldocs!
by ambrus (Abbot) on Aug 02, 2010 at 20:27 UTC

    Come on, perldoc can't only be viewed as a roffed (for a particular screen width) manpage. Why would you force a particular line breaking to the viewer? It's better if their browser does that.

    Converting to html is a better approximation: lists come out fine, but isn't perfect, because code blocks will be converted to pre tags then. Maybe we should have a custom pod2perlmonks converter that is based on the html converter?

[reply]

      Like any text you post to PerlMonks, the answer is quite simple:

      • Put <p>...</p> around non-code paragraphs
      • Put <c>..</c> around code blocks.

      That covers 95% of likely POD to be pasted and is very little work. Preserving links or emphasis is often not an issue and is only a little more effort when warranted.

      Update: And then enclose the whole range in <blockquote>...</blockquote> to indent it apart from the rest of your node, of course.

      - tye        

[reply]
[d/l]
[select]
      Sure, but people use cut&paste for inserting quotes, how do you want to combine this with html-formatting?

      Cheers Rolf

      UPDATE: hmm ... one could use JS to get the HTML of the selection.

[reply]
Re: using <pre> tags for citing perldocs!
by almut (Canon) on Aug 02, 2010 at 16:15 UTC

    If I'm understanding you correctly, you'd prefer <pre> over <code> tags here, because the former don't autowrap long lines (at least by default, unless you fiddle with the style sheet).

    OTOH, as I remember from previous similar discussions, it's mainly for this reason that they're considered a sin...

[reply]
[d/l]
[select]
      what I'm meaning is that autowrapping a text at char 70 (or 72?) which is already wrapped at char 80 isn't that fortunate.

      That's why I suggest change "code" to autowrap at char 80 or to introduce a new tag which autowraps at char 80. (I have problems to imagine displays which can handle 72 chars but not 80)

      At the moment "pre" is the best solution for perldocs.

      Cheers Rolf

[reply]

        I think the idea is that you adjust it in your personal Display Settings ("Code Wrap Length") if you don't like the default.

        (Yes, I agree that - for the average display - 80 might be a more useful default (I've set mine to 100) — but I'm not the one to make the change.)

[reply]
Re: using <pre> tags for citing perldocs!
by aquarium (Curate) on Aug 04, 2010 at 06:03 UTC
    You can refer to more extensive text of documentation with a url to the perldocs. Smaller text is trivial to reformat as needed to put in code tags.
    Theoretically the hosting server could use something like Pygmy or similar package to remove all extra whitespace and apply a consistant formatting style to all code tagged blocks..with caching etc. But then that sounds like too much work and testing.
    I do agree that the automated line breaks with added plus signs are a bit of an eye-sore. Doesn't help also that you can't TAB indent easily when typing a little code snippet.
    the hardest line to type correctly is: stty erase ^H
[reply]

Back to Perl Monks Discussion