On Thu, Oct 19, 2006 at 12:49:58PM +0200, Gour wrote:
> On Wed, 2006-10-18 at 22:48 +0200, Nicolas Maufrais wrote:
>
>
> > I think we should focus on cinelerra documentation. We should find a way
> > to improve the documentation. There are some possibilities. One of them
> > being to copy/paste some part of the wiki into the cinelerra.texi file.
>
> [...]
> > Any comments are welcome. Let's talk about it and try to find some
> > solutions. ;-)
>
> Today I heard that HV manual ("Secrets") is not updated so often, or
> much less than wiki.
>
> So, my point is that it could be easier to start from wiki and merge
> cinelerra.texi with it.
>
> My irc suggestion was to use something like txt2tags (see
> http://txt2tags.sourceforge.net/features.html)
>
> which has simple markup and produces many output formats (XHTML, LaTeX
> etc.), and can be automatized (command tool is available) and it is
> multi-platform written in Python.
What about using the standard GNU tools? Their quality is very good. Did
you have a look at what's written in "Secrets of Cinelerra"? I quote:
"ABOUT THIS MANUAL
This manual is relevant only for the heroinewarrior.com version of
Cinelerra. If you are using the cinelerra.org fork, you should use the
manual for that version. The behavior of different forks is highly
variable.
Organizing information in the easiest manner for users to find out what
they need to know is sort of like cataloging the internet. They've been
trying to get it right for 30 years and will probably keep trying until
the end of time.
There a lot of fragments of documentation scattered throughout the
internet about Cinelerra. This document attempts to combine all the
pieces of information in one piece.
Like the operating system and compiler for a piece of software, the
document writing format is the most important thing in choosing our
document format. We wanted a format which would be readable regardless
of corporate whims and fads. A piece of software which compiles on GCC
and Linux will be usable as long as there are C compilers. Documents
written in Texinfo will be readable as long as there's a C compiler.
After many years of searching for the perfect documentation format we've
arrived at TexInfo. This format can be converted to HTML, printed,
automatically indexed, but most importantly is not bound to any
commercial word processor.
There are no screenshots in this manual. Screenshots become obsolete
quickly and as a result confuse the users. What looks one way in a
screenshot will always look different in the real program because the
real program and the manual are always evolving, never perfectly
synchronized. It is true that manuals should have screenshots, but our
objective in omitting screenshots is to keep the software costs minimal
so you don't have to pay for it. That includes additional labor to
synchronize the manual with the software.
In addition to telling you the basic editing features of Cinelerra this
manual covers tricks that won't be described anywhere else. We're going
to try to come up with certain things you can do with Cinelerra that you
wouldn't think of on your own."
I prefer to use good tools which already proved their quality than
something else which isn't widely used, and probably not as good.
> It is simple enough that no special markup-training is required for new
> doc-contributors, and, at the same time, allowing us to produce offline
> manual (eg. HV doc is often very slow) to be used with (idea from
> another post) Cinelerra's Help button.
I'm not quite sure the "markup-training" is that hard for texinfo. Look
at the cinelerra.texi file, and look at the tags. Here they are:
$ cat cinelerra.texi | grep @ | sed "[EMAIL PROTECTED]@+g" | sed "[EMAIL
PROTECTED]([^
{]*\)[EMAIL PROTECTED]" | grep -v "[)}]" | grep -v "[EMAIL PROTECTED]" | sort -u
@author
@b
@bye
@c
@chapter
@contents
@copyright
@end
@example
@image
@item
@itemize
@menu
@node
@page
@section
@setfilename
@settitle
@sp
@subsection
@subsubsection
@subtitle
@title
@titlepage
@top
@xref
There are only 25 tags, some of them being used just 1 time. Moreover, I
think they're quite easy to dig...
> Finally, having LaTeX means getting 1st class PDF output for offline
> use.
IMO, there's nothing more "classy" than a documentation made from
texinfo. It's simple, well arranged, and easy to read.
> I am not attached for specific tool, but I vote for offline HTML editor
> launchable via Help button and 1st quality PDF.
>
> Let's discuss how to achieve it!
Using the wiki as it is for the moment is a real pain. I mean, the work
that Alex did is very nice indeed. But the server is sooooooo slow! It's
a real pain to edit anything!
Putting everything one 1 page could be nice, not because it'll speed up
the reading on the internet, of course. But because if it's on 1 page
only, we'll be able to easily save it on our hard-drives.
The next step IMO should be to merge the Wiki and Secrets into 1 large
document. That would be the definite reference to look at when looking
for information. The wiki will continue, for sure, but its contents
would be integrated into that large manual.
Cinelerra documentation really need to be improved, and having all the
information splitted over several places brings confusion.
Nicolas
_______________________________________________
Cinelerra mailing list
[email protected]
https://init.linpro.no/mailman/skolelinux.no/listinfo/cinelerra
