discuss: A note about links in documentation
Subject:
Re: A note about links in documentation
From:
"Mariusz Pekala" ####@####.####
Date:
2 Aug 2001 20:30:48 -0000
Message-Id: <00b401c11b91$c5941a30$0201a8c0@wmbr.com.pl>
----- Original Message -----
From: "David Lawyer" ####@####.####
Subject: Re: A note about links in documentation
> On Wed, Aug 01, 2001 at 09:39:25PM +0200, Mariusz Pekala wrote:
> > Hello.
> > Reading some of the documentation I noticed that it's a very popular
> > manner to include a http links in this manner: ...you may download
> > it <a href="http://some.host.org/file">here</a>.
> >
> > This is OK if you read the doc online, but is very annoying if you
> > read a printed document. How do you know 'where' you can
> > download???
>
> By "printed document", do you mean the text rendition of it which
> someone has printed? Or do you mean a pdf of ps that has been
> printed?
In fact I mean the PDF version of a Domain-mini-HOWTO, after I have sent it to the printer and got with me to read in the bus while I am on my way home. :-)
The links are preserved and works good when I am reading the doc on my screen - I can click it with mouse and my viewer (whatever it is) goes in the right place.
What I want (I kindly ask) is that one should do exactly what you say below: "In this case the author needs to give enough information so that one can locate the reference (target of the link) in the plain text version.", but I would love to have it with the internet links.
Two examples:
(Domain-HOWTO)
"The root.hints file is exactly as described in the BIND documentation, or in the DNS HOWTO(link). At the..."
(LDP-Author-Guide)
"5.6. References
There are many guides to writing style available online. Here is a brief list of some of the best:
- Politics and the English Language(link)
- The Elements of style(again a link)
..."
A good example of what I mean is:
(LDP-Author-Guide)
"3.5.2. VIM
http://www.vim.org (link - GOOD ONE!)
No mention of Emacs is ...."
--MP
>
> The text versions should preserve the urls. Please cite the exact
> situation and where the doc is at the LDP site. If it's something
> someone else has converted from the .sgml source, they may have done
> it wrong.
>
> Another problem is where links are put in a doc which link to other
> parts of the same doc. In this case the author needs to give enough
> information so that one can locate the reference (target of the link)
> in the plain text version. The reader may need to use a "find" command
> (or the like).
> >
> > The worst is that the same you can see on the LDP-Author-guide. I
> > hoped, that there I find a clue to use other style: ...you may
> > download it from <a
> > href="http://some.host.org">http://some.host.org</a> ...
> >
> > Please, consider using the second style of links and maybe
> > encouraging this in the LDP-Author-Guide. I believe, some people
> > prefer reading in printed form.
> >
> > --M.P.
> David Lawyer
--
Jest niezly ... i liscik napisze
OnetKomunikator [ http://ok.onet.pl/instaluj.html ]
