Re: Thoughts.

[Kevin Forge <forgeltd@usa.net>]

Donovan Rebbechi wrote:
> 
> > Roger Dingledine wrote:
> 
> the conversion will not be done improperly if the conversion package is
> well written.
>
You are missing the point here.  some of the best documentation (
especially
for beginners ) is written by relative newbis.  Do you really want
someone
without a clue generating docs onles the program to do it is pure
WYSIWYG.
THAT by the way is an important option.  There must be at least one
simple 
word processor like WYSIWYG authoring tool to produce this metafile
format.
Also I would distribute the DOCs as HTML, regardless of what format they
are
initially written in.  Why ?  Because if all else fails you can use Lynx
to
read them.  and in moments of desperation you can use internet explorer
on Windows 95 to peruse the instructions.
Yes it's a scary thought but SEUL at it best will attract mostly Windows
95
veterans.
> 
> Is there any reason why html can not be converted to the other formats
> without data loss ?
>
None whatsoever.  but do we want any new help format ?  
>
> > tags ( like me ) it is still useable since HTML can be generated with
> > simple wisiwig programs ( even Netscape and a slew of Word processors )
> 
> I'm sceptical about the WYSIWYG programs because they create fairly awful
> html. The problem is that to write decent html, you have to know what
> you're writing, not just how what you're writing renders on your
> hardware/software configuration.
> 
> In fact, to enforce consistency in the look of the help system, some kind
> of text file "marked up" to the other formats would be better. For example
> :
> %TaskName       Copy
> %TaskGroup      /KDE/file-management
> %Author         Donovan Rebbechi <elflord@pegasus.rutgers.edu>
> %Description    A tutorial on copying files in KDE
> %Steps
> %1      blah blah blah ...
> 
> OK, I ripped this idea off the RPM spec file thing. The point is that html
> offers too much scope for the author to put in junk that's not needed or
> wanted, and it will take a more restrictive file format to be effective.
> This does not require much of the author, since some-one not familiar with
> the format can write one of these things by editing another one, since the
> format is very canned.
>
Makes a lot of sense.  and ?I can see how this would be easy to
translate 
into HTML.
>
> > > What's up with the linux doc project?
> 
> speaking of which, the "linux user's guide", by Larry Greenfield , is
> worth looking at for task help. in my view, the best for beginners out of
> the LDP docs.
>
Too bad my AP2250 isn't up to such jobs ( especially with a severely
broken
filter ) 
>
> > > man pages ought to be worked on,
> 
> the tar page is a mess (-:
>
Then they should be fixed.  but do we care ?  After all, all SEUL users
will want to do with tar are the basics.
tar -zxvf foo.tgz etc... 
>
> > or are they not working much on man
> > > pages these days?
> 
> I use linux and solaris and the man pages are (by and large) no different.
> Most of the man pages seem to come straight from the authors.
> 
> > We shouldn't bother with maintaining man pages.  While some are a little
> 
> Good point. In instances where the man page is bad (again , tar is my
> favourite example), task help is the best remedy, not more man pages.
>
Ahh... 
 
> I found the content OK, but I couldn't use the browser. Info wasn't
> available to me until I had KDEhelp! It's ironic to have a help system
> with a steep learning curve !
>
An example of a pointless exercise.  Like a conventional automobile with
no gas tank.  Sure you can drive it.  but it may be easier to just walk.
>
> Another point with "/usr/doc" is that it's not just for help files, all
> the licensing information goes there. THe reason why there's no standard
> place to put the "help" system other than info and man, is because there
> was no such thing prior to recent linux distributions.
>
Which is why moving the stuff that is in there now to /usr/doc/pachages
is such a brilliant idea.  Other distributions may follow us. 
especially 
if we somehow categorize them under that with a sort of hierarchy. 
>
> > No read my response to question number 2 and you will see that
> > task-help is what I think needs to be written.
> 
> ABsolutely. task-help is the kind of to-the-point concise and simple
> information that SEUL's users need.
> 
I have just started to try my hand at task help writing ( a KDE On
RedHat 5.0 HOWTO ).  First I list the assumptions about the system
( At least the standard install with X and the development stuff ).
then I list all the files that will be needed.  Modern GUI E-Mail progs
render http://www.seul.org/ as a hiperlink even though the E-Mail is
plain text.  So I listed the locations that way.  
Finally I went through what needed to be done in a numbered list. 
This is the 4th instruction on the list and shows the kind of caned
approach.

4 : Modify the /etc/profile
edit /etc/bashrc 
  replace "edit" with whatever editor you use ... I like joe )
  add these lines to /etc/profile ( the KDE and QT documentation 
  will explain what they all do )

# Begin QT/KDE additions
KDEDIR=/opt/kde
QTDIR=/usr/local/qt
PATH=$QTDIR/bin:$PATH
MANPATH=$QTDIR/man:$MANPATH
LD_LIBRARY_PATH=$QTDIR/lib:$KDEDIR/lib:$LD_LIBRARY_PATH
LIBRARY_PATH=$LD_LIBRARY_PATH
CPLUS_INCLUDE_PATH=$QTDIR/include:$CPLUS_INCLUDE_PATH
export QTDIR PATH MANPATH LD_LIBRARY_PATH LIBRARY_PATH
export CPLUS_INCLUDE_PATH KDEDIR
# End QT/KDE additions


> -- Donovan

-- 
Through the the Firewall, out the ruter, down the T1, bounced from
satellite.  ... Nothing but net.