[Fedora-electronic-lab] User documentation (was Re:Dead Upstream what should we do ?)

Chitlesh GOORAH chitlesh at fedoraproject.org
Sat Dec 5 11:55:02 UTC 2009

On Sat, Dec 5, 2009 at 6:31 AM, Shakthi Kannan  wrote:
> Can this be done in the RPM packaging process?
> We know the .spec file mentions the -doc files. If we are able to list
> and put the location of all these -doc files for a package in a text
> file, say package.guide, similar to a .desktop file, an application
> can read all these package.guide files from a single directory (say,
> /usr/share/guide/*.guide) and show it to the user.


Yes, we can. It's up to us to maintain such things. But listing all
the doc files off a package will give a lot of outputs, userguides,
example directories containing a lot of files etc.

# case 1

So at first we need to setup a simple guideline for packaging the docs
and work with upstream to improve the quality of doc distribution.

Let's say to begin with we ensure that in the doc directory
/usr/share/doc/NAME-VERSION/ we have these files:
 * userguide.pdf
 * examples/ directory
   * example1
   * example2

hence we can easily sketch a minor script to look for those items and
flush its output into a latex file.

# case 2

Start writing a userguide in latex. Let's say, in the PCB section, if
we point to pcb.pdf coming with the package, we can exact a script
against our latex file which will automatically go and search for the
exact file path and create a link on the "pcb.pdf" text on our latex
file (using the url latex package).

My thoughts:
Case 1 : we have to work very hard to ensure consistency with all the
FEL packages. Time would be a major concern for me.
Case 2 : one central location for all the docs (our latex file) and
for every release, we execute the script to update and create a pdf.

What do you think ?


More information about the Fedora-electronic-lab-list mailing list