Some technical suggestions

[Stein Gjoen <sgjoen@mail.nyx.net>]

(I see some have banned online.no so I am sending this using
another of my email addresses.)

This is a summary and an update of some of my ideas on how to make
the LDP works more useful for the end users, mainly by integrating
HOWTOs and man pages more closely and by simplifying effective
searches.

If anyone feels they have seen this before you are not entirely mistaken
but there are some updates here too.

	BACKGROUND
	==========

The main problem is that the HOWTOs just are not visible enough. Just take 
a look on news:comp.os.linux.setup and you will find many asking for what 
is already described in the LDP documents. I spent a week scanning that 
group for topics relevant to my own HOWTO (the Multi Disk HOWTO) and the 
result was depressing. A quick search for relevant documentation on the 
major web search engines did not show my own HOWTO in the first few pages, 
so I cannot not putting all the blame on the newbies.

	SEARCHING
	=========

Now that we all use indexing (right?) I feel only a little bit extra
would make the HOWTOs more accessible by being searchable:

 - web search engines:

All documents are on the net and searchable from most web indexing
machines. Yet the markup used today has no means of creating META tags
with the most important keywords which could score a particular HOWTO
higher up on the list. I feel there should be separate keyword tags
for each HTML file to make searches more precise. This could also make
more people aware of the LDP.

If someone promoted the HOWTO pages on web indexers this would make it
even more efficient. As an experiment I used a free promotor web page
and added my HOWTO to about 20 search engines. My hit rate had been
about 20-50 per day and after 2 weeks it is now steady at 100-150 hits
per day. With even more intensive search engine registration I now
get 150 - 300 hits per day. Not much but still better than nothing.
Has www.linuxdoc.org been registered? I cannot remember having seen it
in news:comp.os.linux.announce either.

What is done to promote the LDP pages today? An automated mass
registration with some search engines and joining up with Freshmeat
should help. Some search engines like Google measure relevance of a
document by counting links leading into it, making registration even
more productive.

Very recently I found out that a disk manufacturer has linked to my
HOWTO; I guess with a name like Multi Disk HOWTO there are good
arguments to buy many disks. How common this is I do not know but if
this becomes more common we can generate even more interest in the
LDP, this time from companies.

 - local searching:

Most new users learn of the "man -k keyword" type of searches
which generally are fast and efficient. Yet this has the huge
disadvantages in that it misses out completely on the entire
LPD library. From reading newsgroups I get the feeling many
use keyword searches without realising they are forgetting the
LDP work. Redhat does admittedly include a search engine that
scans most types of information sources but this could be done
much simpler.

I propose "sgml2apropos", that from the same keyword tags
as used for creating keyword tags for webcrawlers
create a rudimentary man page containing keywords for the
makewhatis database as well as a pointer to the location of
the HOWTO itself. Possibly we would need a new manpage
extention, for instance "sgml2apropos myhowto.sgml" would
create a file "myhowto.ldp" in the appropriate manpage
directory. These will in turned be included in the whatis
database for keywork searches. Using the abstract section of
the HOWTO as the body of the manpage would also be helpful.

Also a manpage for LDP (say "intro.ldp") that uses a few
chioce keywords such as intro, help, document; will improve
the LDP and HOWTO visibility.

 - tags for integration

Also if I may make an suggestion, make the <file> tag into
a clickable link in the HTML version ( file:///somewhere/else.txt )
while using non proportional fonts in the postscript version.
On an internet website such as linuxdoc this would need to point
to a dummy page of some sort.

Likewise if the command tag (<cmd> ?) could somehow be linked to a
man page viewer we could integrate the man pages with the HOWTOs.
This would need a parameter to state the section of the man page.
There is already a website that holds online man pages from the
LDP so it should be possible to integrate an internet website
with online man pages, check out
	http://www.ctyme.com/linuxdoc.htm

Someone has made an online Linux encyclopedia which I found
very useful and comprehenive. The author stated he is not happy
with its low visibility, so why not join forces and invite him
and his "Pedia" on board? It already contains many links to HOWTOs
so we should perhaps help by reciprocating. Check
	http://members.aa.net/~swear/pedia/index.html




	HELP FILES
	==========

I believe we need to add a SMALL text file into /etc/skel/ so all
beginners get a starting point. How about this:

help.txt
-----
For information and help, check the documentation directories at
/usr/doc and /usr/share/doc and especially the HOWTO subdirectory there.
There is also a manual, use the command 'man man' to learn how to use it
and note that you can search using keywords 'man -k <keyword>'.

On the internet you will find updated information at
http://www.linuxdoc.org/
-----

Also I believe there should be an intro man page for the LDP, something
very roughly like this (not properly formatted with groff):

-----
intro.ldp

Intro - Introduction to Linux documentation project

INTRODUCTION

The Linux Documentation Project (LDP) produces practical documentation
for Linux systems, including
 - System Administrators Guide
 - HOWTOs and mini-HOWTOs, single task oriented practical hands-on guides
 - man pages, manuals for comamnds, libraries etc.
 - and more

Documentation can be found in the /usr/doc/HOWTO or /urs/share/HOWTO
and mini-HOWTOs are found in the mini/ subdirectory below the HOWTO/
directory on your system.

Manuals in the form of man pages are accessed by the 'man' command,
which of course has its own man page: try 'man man' (type the text
between, excluding the inverted commas).

FILES
	/usr/doc/HOWTO		for FSSTND systems
	/usr/share/doc/HOWTO	for FHS systems

BUGS

If any, report to the individual authors, see heading in each HOWTO.
Failing that, contact (insert email address here)

ONLINE
	LDP home page:	http://www.linuxdoc.org/

-----

	SUBMISSION
	==========

In addition to monthly posts to news:comp.os.linux.answers I suggest
using news:comp.os.linux.announce to announce new or updated HOWTOs
as well as linking up with Freshmeat, who also does some minimal
tracking. As a bonus this means getting on the announcement page of
Linux Weekly News http://lwn.net/ which secures broad readership.
Make this automatic and it should save the authors some work.


	SUMMARY
	=======

If we can make such an integration work well both on the internet
as well as on local disks I believe we really have something to
present at a conference that people will pay attention to.


So what do you think?

   Stein Gjoen


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org