discuss: A note about links in documentation
Subject:
Re: A note about links in documentation
From:
David Lawyer ####@####.####
Date:
14 Aug 2001 06:45:38 -0000
Message-Id: <20010813213213.A1164@lafn.org>
On Fri, Aug 03, 2001 at 08:22:09PM +0200, Mariusz Pekala wrote:
> U?ytkownik "Guylhem Aznar" ####@####.#### napisa? w wiadomo?ci ####@####.####
> > > 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. :-)
> >
> > This looks like an error in the linuxdoc sgml or docbook version which
> > is translated to every file, including pdf.
> >
> > There are banners saying the URL and the text message that should
> > replace it. Obviously, it was not parsed correctly.
>
> Hmm.. I am not sure.. I suppose that the authors are just writing
> this way. I have no experience (yet) with DocBook or LinuxDoc, so I
> cannot check if my supposition is right, but it seems to me that if
> I see a link of this form (in html format - it should be clear what
> I mean): ... you get it <a href="http://somewhere.org">here</a> ...
> then it was just written this way, and not incorrectly parsed by
> some tool.
Yes, it was written this way but the text rendition is supposed to
explicitly show the url http://somewhere.org. On all the plain text
versions produced using LinuxDoc or DocBook, the url is shown even if
its not shown in the html version. If one is reading the html version
off-line, there is always a way to look at the url of a link.
>
> I believe that a good style would be if such links (maybe I use the
> word 'link' in misleading context? My English isn't perfect...) were
> typed in similar way: (again html style): ...you get it at the <a
> href="http://somewhere.org">http://somewhere.com</a>...
I don't think so. People reading the html versions are often better
served by clicking on a meaningful name than on a url. But in some
cases it's nice to read the url so it's up to the author to determine
if s/he wants to have html viewers see it. What's important is to fix
the conversion so that this doesn't happen when you print from PDF.
Do others who print from PDF have this problem? If the problem is
widespread and can't be fixed, then perhaps your suggestion is good
(or at least good until the PDF print conversion can be fixed).
David Lawyer
> Maybe it would be good to suggest this kind of links 'citing' in
> documentation? Surely it would make happier people that prefer
> reading from sheets of paper :-)
>
> --Mariusz
