Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

Suggestion for new shortcut-tags: [man://] and [mskb://]

by Perlbotics (Bishop)
on Oct 28, 2008 at 16:35 UTC ( [id://720039]=monkdiscuss: print w/replies, xml ) Need Help??

While trying to look-up a shortcut for man-pages in What shortcuts can I use for linking to other information?, I noticed that there is no such thing as a [man://] tag. Although, I know that there are various flavours of Unix, it would be convenient to point to a site such as http://www.freebsd.org/cgi/man.cgi for further reading. E.g. [man://env]env could be linked to http://www.freebsd.org/cgi/man.cgi?query=env, which will present a default man-page for FreeBSD. There, the reader can select the same man-page for another Unix flavour if desired.

Potential variations could include (with env as an example):

[man://env]env
look-up 'env' for any Unix (FreeBSD by default)
(→ http://www.freebsd.org/cgi/man.cgi?query=env)
[man://env(1)]env(1)
look-up 'env' in section (1) / note the CGI NVP: sektion=1 (not(!) section)
(→ http://www.freebsd.org/cgi/man.cgi?query=env&sektion=1)
[man1://env]env(1)
same: look-up 'env' in section (1) / analogue: man2, man3, etc.
[man1://env|env (1) manpage]env (1) manpage
same but user defined text
[man://env(SunOS 5.10)]env (SunOS 5.10)
specification of a distinct OS - could be challenging to implement reliably / note the CGI NVP: manpath=SunOS+5.10
(→ http://www.freebsd.org/cgi/man.cgi?query=env&manpath=SunOS+5.10)
[apropos://env](apropos) env
don't know if that makes sense, but if [man://] is possible, [apropos://] is easy / note the CGI NVP: apropos=1
(→ http://www.freebsd.org/cgi/man.cgi?query=env&apropos=1)
At least the [man://] and [man1://] [man2://] ... variants should be straightforward to implement.
The freebsd service seems to exist for several years, so there is a little bit of confidence that it will be available in the future.

For Windows related references to the KB MS Knowledge Base, the [mskb://] tag could be useful. E.g. [mskb://245225]MSKB 245225 being a link to http://support.microsoft.com/kb/245225. Analogue: [mskb://245225|HOW TO: Configure and Test a PERL Script with IIS 4.0, 5.0, 5.1, and 6.0]HOW TO: Configure and Test a PERL Script with IIS 4.0, 5.0, 5.1, and 6.0.

I am not sure if linking to those sites might have some legal implications...

Update: NVP = Name/Value Pair, nowadays Attribute/Value Pair
Update2: samples highlighting the differences added; links for CGI, NVP, and KB added.
Update3: Summary and update here.
Update4: Today, 16-mar-2009, the [man://] shortcut has become reality! Thanks to pmdev - especially jdporter - for implementing this suggestion.

Replies are listed 'Best First'.
Re: Suggestion for new shortcut-tags: [man://] and [mskb://]
by moritz (Cardinal) on Oct 29, 2008 at 09:04 UTC
    I quite like the idea of the [man://...] and [man://program (1)] shortcuts.

    I'm not sure about [man1://] - it's quite intuitive, but it goes against the current design of having one pseudo-protocol per link type. So I'd rather go with [man://program (1)] instead (but don't really mind either way).

    As for the mskb links: I've never posted a link to one of them (but then again I don't use Windows either), and haven't seen particularly many here in posts or in the Chatterbox. But I don't think they would do any harm either, so I'm not against it either.

      Well, as long as they are formatted as URLs, why not
      [man://env] # Any 'env' manual page. [man://env/1] # Any 'env' manual page from section 1 [man://env/1/Solaris] # Solaris 'env' manual page from section 1 [man://env//Solaris] # Solaris 'env' manual page - any section
        I really like this version best out of the ones so far proposed. I have a couple of suggestions that might improve it even more.

        I really don't like anything made to look like a URL to have a double solidus (what W3 likes to use for "forward slash") in it. Yes, I know the format used for a shortcut wouldn't have to be directly related to the actual URL to which it refers. That would be very unlikely anyway unless someone at PM controlled the sites referenced. It's just a strong habit to eschew syntax in a URL-alike that wouldn't actually be valid for a URL. Perhaps one of these would be nicer for every section of a particular OS:

        [man://env/*/Solaris] # I like the "any" mnemonic [man://ksh/?/Linux] # looks like a query string [man://bash/any/OpenServer] # kidding about OpenServer [man://ncftp/all/AIX] [man://lynx/-/OSX/10.5.2]
        The question mark works for two reasons: it makes what comes after it just look like a query string, and it's a one character wildcard in many contexts (with most manual sections being represented by a single character). The asterisk is pretty plain: anything goes here. The "any" and "all" are pretty self-explanatory. The ASCII minus sign (doing double duty and standing in for dash here, as it often does) is just a common URL member character that happens to be a valid directory name (even if it's not straightforward to 'cd' to Bash) and valid URL segment.

        Also, a simple one in your scheme since people have mentioned specific versions of the OS:

        [man://env/1/Solaris/5.10]
        That's still an issue for Linux, since different distributions have different numbering schemes and such. Perhaps:
        [man://env/1/Linux/RHEL/5] [man://env/1/Linux/OpenSuse/9]
        Or perhaps a few of the most popular Linux distros are considered their own OSes:
        [man://env/1/RHEL/4] [man://bash/*/Ubuntu/8.10] [man://for/any/Puppy/4.1] # What? It's very popular in my office. ;-)

        All of this leads to the inevitable maintenance questions, though. Who chooses which OSes are included? Who chooses which site to use for the man page links? What happens when that site goes down or changes its URL structure? Who's going to do the work on the PM end, and what Perl-related or PM-related resource would have had more attention if not for this? The MS Knowledge Base shortcut seems reasonable from the maintenance standpoint, as it's a single number reference to a single fairly stable site.

        Better, but I think it would be more intuitive if the format for giving the section would be like [man://1 env] or [man://env(1)]: the first one is similar the the syntax of the command-line man utility which you invoke as man env or man 1 env, the second is like the header on the formatted manpages.

Re: Suggestion for new shortcut-tags: [man://] and [mskb://]
by Perlbotics (Bishop) on Oct 30, 2008 at 18:37 UTC

    After fiddling around a bit with the FreeBSD man.cgi interface, I came up with a small heuristic (argl!) for specifying the OS and a Perl program that created the table below. It shall provide an impression of what the results might look like and summarise the feedback, I've got so far (thanks).

    My assumptions:
    • the vast majority of users (of the minority that requires UNIX Man Pages anyhow) will need something like [man://program] only
    • a section is rarely necessary, e.g. for passwd (1+5)
    • someone requiring a special manual section for a distinct version of a given OS should use a direct link - as offered at the bottom of a FreeBSD manpage: e.g http://www.freebsd.org/cgi/man.cgi?query=env&manpath=Darwin+1.3.1%2fx86
    • maintenance overhead at PM should be close to nothing, thus the release of an OS is not processed
    • format: [man://PROG (opt. SECTION) (opt. OS)], order of OS and SECTION insignificant
    • optional (\d+) is a hint for a SECTION
    • optional (\D+) is a hint for an OS plus optional release (latter: ignored!); The FreeBSD site is quite good at guessing the current OS for a given manpath-attribute without a release number.
    • currently, the OS is simply uppercased (e.g. SUSE instead of SuSE)
    • [manX://abc] is offered as convenience shortcut for [man://abc (X)]
    • whitespace-tolerant, case-tolerant
    • class="man", class="mskb" for individual styling
    • using the format [man://prog (section) (os rel)] or [man://prog/section/os/rel] is mainly a matter of taste..., so I started with my favourite pattern
    • personally, I think the reference should contain no whitespaces
    • restriction of current implementation: no nested (...(..)..) or [..[..]..] allowed
    • handling of MSKB entries is trivial
    • ....
    Some testcases (including ill. formatted entries) below. Some very simple heuristics are applied to find the manpath attribute for a given Unix flavour keeping the maintenance overhead small at PerlMonks. If the heuristic fails, the FreeBSD site will fallback to the default OS (FreeBSD) - which is OK for me. Although, abandoning the requirement to identify a certain OS would simplify the maintenance burden significantly. The lookup-table is:
    my %patch = ('hp-ux' => 'hpux', x => 'x11', plan => 'plan9', osf => 'osf1', xfree => 'xfree86', minix => 'Minix+2.0', opensuse => 'suse', rhel => 'redhat', );

    So, how shall we proceed?

    Update: Right, RHEL is not identical to RedHat Linux, but the intention was to come close to the family, which is rather RedHat than FreeBSD... However, it can be corrected by removing the rhel => 'redhat' entry from the hash above (see: mr_mischief's comment).
    Update2: If you like to experiment with the effect of the man and mskb styles, go to your Display Settings and add something to the On-Site CSS Markup - section, e.g. (nobody says it has to look good!)

    .man { border: 1px solid #ff0000; background-color: #e6e6e6; } .mskb { border: 1px dotted #0000ff; background-color: #e6e6e6; }


    InputRenderedLink-Layout
    shell shell <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=sh&format=html&manpath=Minix+2.0">shell</a>
    env man:env <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html">man:env</a>
    env(1) man:env(1) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&sektion=1">man:env(1)</a>
    env (1) man:env(1) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&sektion=1">man:env(1)</a>
    [man1://env] man:env(1) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&sektion=1">man:env(1)</a>
    env (sunos) SUNOS:env <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&manpath=sunos">SUNOS:env</a>
    env (sunos) SUNOS:env <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&manpath=sunos">SUNOS:env</a>
    env (sOlarIS 77) SOLARIS_77:env <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&manpath=solaris">SOLARIS_77:env</a>
    env(1)(susE 55.11) SUSE_55.11:env(1) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&sektion=1&manpath=suse">SUSE_55.11:env(1)</a>
    passwd (hp-ux) (5) HP-UX:passwd(5) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=passwd&format=html&sektion=5&manpath=hpux">HP-UX:passwd(5)</a>
    [man1://passwd(5) (redhat)| should override section 1 by 5] should override section 1 by 5 <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=passwd&format=html&sektion=5&manpath=redhat">should override section 1 by 5</a>
    man page of env section(1) man page of env section(1) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&sektion=1">man page of env section(1)</a>
    man page of env section(1)|blah man page of env section(1)|blah <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=env&format=html&sektion=1">man page of env section(1)|blah</a>
    passwd ( 1 ) ( Solaris) SOLARIS:passwd(1) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=passwd&format=html&sektion=1&manpath=solaris">SOLARIS:passwd(1)</a>
    passwd(5)(suse) SUSE:passwd(5) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=passwd&format=html&sektion=5&manpath=suse">SUSE:passwd(5)</a>
    passwd(5)(rhel) RHEL:passwd(5) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=passwd&format=html&sektion=5&manpath=redhat">RHEL:passwd(5)</a>
    passwd (5) (opensuse) OPENSUSE:passwd(5) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=passwd&format=html&sektion=5&manpath=suse">OPENSUSE:passwd(5)</a>
    passwd (5) (openSuSE) (11) OPENSUSE:passwd(11)(5) <a class="man" href="http://www.freebsd.org/cgi/man.cgi?query=passwd(11)&format=html&sektion=5&manpath=suse">OPENSUSE:passwd(11)(5)</a>
    [mskb://245225] MSKB:245225 <a class="mskb" href="http://support.microsoft.com/=kb/245225">MSKB:245225</a>
    [mskb:// 24 5 225 ] MSKB:245225 <a class="mskb" href="http://support.microsoft.com/=kb/245225">MSKB:245225</a>
    [msKB:// 24 5225| ] MSKB:245225 <a class="mskb" href="http://support.microsoft.com/=kb/245225">MSKB:245225</a>
    [mskb://245225 | Perl and IE ] Perl and IE <a class="mskb" href="http://support.microsoft.com/=kb/245225">Perl and IE</a>
      The RedHat links do not appear to be RHEL as you seem to assume. They appear to be for "RedHat Linux" versions 4.2 through 9 which predate RedHat Enterprise Linux 1 and Fedora Core 1.
Re: Suggestion for new shortcut-tags: [man://] and [mskb://]
by jdporter (Chancellor) on Oct 28, 2008 at 20:50 UTC
    What does "CGI NVP" mean?

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others lurking in the Monastery: (2)
As of 2024-03-19 07:14 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found