Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Request for an update to: What shortcuts can I use for linking to other information?

by taint (Chaplain)
on Dec 03, 2013 at 17:19 UTC ( #1065461=monkdiscuss: print w/ replies, xml ) Need Help??

Greetings, Monks. I recently had a "shoot out" with marto. I think we both had valid points. It all stemmed from the shortcut link to the FreeBSD man pages (note I didn't just link man to the man pages ;)

Point(s) were. I assumed, that because the link was to the FreeBSD man pages, that the returned results would be from the FreeBSD commands. But (counter intuitively) they are to SuSE Linux. This came as a bit of a shock to me. As the link to the PerlMonks short cuts page
What shortcuts can I use for linking to other information?
under:

Unix man pages: A specific command: [man://command name] Search form: [man://] (no args)
makes no mention that the links points to Linux versions of the commands. But rather, indicates they're UNIX man pages.

Personally, I find/found this to be a bit counter intuitive. As such, I'd like to purpose an addition to that section. That clarifies the expected return results. eg; man pages for SuSE Linux.

Not particularly a big deal. But seems that it would be more intuitive, if users knew in advance that the results weren't necessarily from FreeBSD, even tho the link points there.

Well. Thanks for your consideration, and best wishes.

--Chris

UPDATE; converted quoted node id, to proper link via [id://]

#!/usr/bin/perl -Tw
use Perl::Always or die;
my $perl_version = (5.12.5);
print $perl_version;

Comment on Request for an update to: What shortcuts can I use for linking to other information?
Download Code
Re: Request for an update to: What shortcuts can I use for linking to other information?
by kcott (Abbot) on Dec 04, 2013 at 07:57 UTC

    G'day Chris,

    While I think that you probably have a valid point embedded in your post, it's vague, shows little in the way of research and contains errors.

    Your post starts with a paragraph containing: "It all stemmed from the shortcut link to the FreeBSD man pages ..." — that seemed like a good place to start for background information. Unfortunately, that link (resolved to 'http://www.perlmonks.org/?node=url%3Dhttp%3A%2F%2Ffreebed.org') leads to a Super Search page with no matches; I changed freebed to freebsd but got much the same (i.e. Super Search with no matches). [Note: other monks may get something other than the www.perlmonks.org (unless that was hard-coded). There's six possibilities: com, net and org with or without the www.]

    Also, I don't know what you mean by "(note I didn't just link man to the man pages ;)". So, by the end of the first paragraph, not only do I have no background, I don't actually know what you're talking about.

    In your next paragraph, you show a URL as code: "http://www.perlmonks.org/?node_id=43037". Not only have you hard-coded www.perlmonks.org, you don't actually provide a link. Your request for a change was all about "What shortcuts can I use for linking to other information?" and a link to that page should have been provided. I marked up that link as '[43037|What shortcuts can I use for linking to other information?]'. Follow that link to find others ways to do this. Then read further down to:

    All Links Within PerlMonks Should Be Relative

    ... do not include the http://www.perlmonks.org part!

    Now onto the main issue.

    If you use this markup ([man://]), you get this link (UNIX Man Pages), which leads to 'http://www.freebsd.org/cgi/man.cgi'. This is the "Search form" mentioned in the current documentation. Here you'll find a drop-down list with dozens (possibly hundreds - I didn't count them) of *nix flavours and versions (the current default being: "FreeBSD 9.2-RELEASE").

    You could type in ls and Submit, which would give you 'http://www.freebsd.org/cgi/man.cgi?query=ls&apropos=0&sektion=0&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html'; or, you could change the default to, say, "SuSE Linux/i386 11.3" and get 'http://www.freebsd.org/cgi/man.cgi?query=ls&apropos=0&sektion=0&manpath=SuSE+Linux%2Fi386+11.3&arch=default&format=html'.

    If you use this markup ([man://ls]), you get this link (ls), which leads to 'http://www.freebsd.org/cgi/man.cgi?query=ls&manpath=SuSE+Linux/i386+11.3'. While there are minor differences in the query string, this is basically the same page you get with "SuSE Linux/i386 11.3" (as shown in the last paragraph).

    I think your request boils down to one or more of the following.

    • Change the [man://...] documentation so it is more like [dict://...] which has: "Currently we use Dict.org, ...".
    • Change how [man://...] works such that it uses whatever default http://www.freebsd.org/cgi/man.cgi uses.
    • Change how [man://...] works such that it uses something other than what's currently used by PerlMonks (i.e. "SuSE Linux/i386 11.3").
    • Extend the [man://...] functionality to allow a choice of *nix flavours/versions.

    My guess (and I stress guess) is that the first of those is easy to do, may well be received favourably, and could happen in a short time span; the second and third require more work, would need a consensus which might be difficult to agree upon, and may not happen soon; the last — well, I wouldn't hold my breath.

    While I'd consider your eagerness to highlight (at least what you consider to be) issues is probably a good thing; you do need to do some research and present a well thought out plan rather than, what appears to be, a knee-jerk reaction to a CB discussion (or wherever your "shoot out with marto" occurred [something else not documented in your post]).

    Finally, please [ preview ], multiple times if necessary, ensuring you've checked all links, before hitting [ create ].

    -- Ken

      Greetings, kcott. I would like to start this note with an enormous apology, to you, and others whom might have struggled the way you apparently did, untangling the way I presented my proposal. I'm terribly sorry. While I do know better. I'm afraid I was a bit keyed up at the time I wrote it. Rather that walk away from it for an hour, and come back to it with a clear head, and set of eyes.

      That said. For the sake of clarity;
      Your assessment is correct -- congratulations, it wasn't easy. ;)
      I have, and have since heavily hacked, the original script FreeBSD currently uses. It has... just a sec, I'll check...better, I'll list them..never mind. The copy I maintain provides man pages for 250 versions of Operating systems. If I get the <readmore> right, you can see them all below:

      In fact I even have the UNIX (VAX) tapes. I only listed them all here for clarity.
      Point being, while I don't know how many OS versions FreeBSD currently maintains. I'm sure it's at least ~150. So I guess what I'm trying to get to here is, given that there are so many different OS's and versions. Not everyone will choose the same one. So it's a matter of which man pages the Monks are willing, or want to support. And then, clarify how to access them. No? Consolidation is somewhat easy, given that modern Macintosh uses BSD as their base. Then there's Linux. While there are seemingly a gazillion different "dists" the commands are almost identical. But different from BSD. Windows, I'm afraid, is out of the question. Unless you want to consider MinGW. In which case Red Hat Linux pretty much covers it. So essentially that leaves 2;
      * POSIX (UNIX/BSD)
      * NONPOSIX (Linux)
      I have no idea how FreeBSD munges their URI's, and I clearly have no idea how the Monks manage the shortcut. But I keep mine simple
      /man/? and
      /man? return the same. If I have to ferret the data from infopages
      /man/?query=
      Having had some time to think about it. It seemed to me, that perhaps a good way to handle the differences might be as simple as
      [lman://] for Linux, and
      [man://] for UNIX/BSD
      But, then again, I have no idea how the Monks arrive at the shortcut, nor how I will know which (UNIX, or Linux) man page I'll get, when using the shortcut. If it's of any help, and the Monks even wish to pursue such an endevour (man v man). I could set up a domain that does nothing but serve man/info pages. I've been hosting for well over 20yrs, and ran BBS's before that. So I guess what I'm suggesting, is if the Monks think it'd be helpful, I could host a sort of "Monks man pages" site. That did nothing more than provide man/info pages for PerlMonks. Just thought it might simplify this matter. As they would be guaranteed some measure of control over the content returned.

      Other than that. I can't think of any other better way to describe it. I dearly hope I was clearer, more concise this time. :)

      As always, best wishes, and thank you very much for all the time, and effort you put into your reply, kcott.

      --Chris

      #!/usr/bin/perl -Tw
      use Perl::Always or die;
      my $perl_version = (5.12.5);
      print $perl_version;

      The context for this is that I reported that the link they created didn't work, going on to point out that they clearly hadn't tested the link because it did not do what they assumed it would. This was ignored a few times until I highlighted the section of the URL causing confusion. Here we see more untested links and an point barely communicated. Simliar to A thought for the leader on SOPW, where I question what exactly they're trying to suggest, given their claim that their point is "obvious" to them.

      "While I'd consider your eagerness to highlight (at least what you consider to be) issues is probably a good thing; you do need to do some research and present a well thought out plan rather than, what appears to be, a knee-jerk reaction to a CB discussion"

      I appreciate that English may not be their first language, but unless they take the time to explain what they mean in a way that people can understand the situation will occur again, as you have pointed out. This may mean not being in such a rush to post/respond, not making assumptions, consider what someone has told you before formulating a reply, think some more about what exactly you want to say, compose a reply, preview it, test links, post.

        Yes, marto. I think it's fair to say, I was so focused on the tree. I was unable to see the forest. I regret not having stepped away, as I normally would have. Before responding. :/

        But then again. I also think that clarity works both ways. IMHO the man page shortcut thing should at least be better clarified on the What shortcuts can I use for linking to other information? page. Even if no other changes to it, are on the horizon. No?

        Best wishes.

        --Chris

        #!/usr/bin/perl -Tw
        use Perl::Always or die;
        my $perl_version = (5.12.5);
        print $perl_version;
Re: Request for an update to: What shortcuts can I use for linking to other information?
by sundialsvc4 (Abbot) on Dec 10, 2013 at 16:42 UTC

    “Staleness” of references, as with “references that will be misinterpreted by the person who tries to follow them,” are simply issues with the Internet at large.   Nothing specific to Perl here.   We have all read “terse” postings which refer to an Internet article that no longer exists.

    Therefore, I’d just suggest ... “don’t particularly [try to] use shortcuts.”   Include, for example, the title and author of the web-page that you wish to reference, as well as a brief synopsis of what it says.   If you cite a man page, then also <blockquote> the most relevant piece of text that you are intending to cite.   In other words, write the comment or post for posterity.   Summarize your conclusions.   Give your contribution what it will need in order to still be relevant years from now, even if it is “the last man standing.”

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://1065461]
Approved by marto
Front-paged by Old_Gray_Bear
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others meditating upon the Monastery: (5)
As of 2014-12-25 14:42 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (160 votes), past polls