On Fri, Dec 4, 2009 at 7:50 PM, Shakthi Kannan wrote:
Just want to discuss this further as our list of packages is growing day-by-day:
Yes userguides are currently one of your weaknesses. Let's create another thread for this as we definitely got to find a suitable solution for the long term.
- Whatever documentation made for a particular software can be pushed
upstream, so we keep track of only one set of sources. We will do documentation in LaTeX or DocBook, so we abstract content with presentation, and it will greatly help us in the long run.
+1 documentation should be pushed to upstream
I would tend to opt for LaTex as most of our upstream developers like to keep their documentation in text format. Having that said, what should we do for other tools which upstream ships loads of documentation in OOo formats e.g kicad-doc ?
As we know Latex gives one the opportunity to create documents in any type of format e.g pdf, dvi, ps ... If we are to ship the same contents in different formats, we should also bundle all the plugins for these formats. In FEL-12, I didn't think about this and by default (on the livedvd) one cannot read .dvi files with evince, because I missed the package evince-dvi on the livedvd (sorry by the way :) ). The more we add such type of dependencies to the livedvd the more * time we have to allocate for the livedvd's testing * time we have to allocate for package reviews * the size the livedvd will be. * the more dependencies they will pull. So here a decision should be made. If it was for me, pdf format is enough. What do you think ?
- In Yelp, we can provide links to all relevant installed package
documentation? If that can be done, it will only be linking to the respective files? or else we will need something similar in the lines of .desktop files that can simply pin-point to where the doc/, man/, info/ pages for each software/tool that is shipped, and are independent of desktop environments.
I have no idea if linking to specific files is possible. In the wiki pages I'm editing on https://fedorahosted.org/fedora-electronic-lab/wiki/Digital, I'm pointing to these type of commands :
$ man XXXXX or $ rpm -qd XXXXXX
example in : https://fedorahosted.org/fedora-electronic-lab/wiki/Digital/iverilog
Pointing to specific files would be great for the user, but hard on us. Each time upstream add/remove docs, the packager will have to update this yelp correctly.
- We will also need to provide documentation on suggested workflows
with various tools that are shipped, so people can follow it.
This is coupled with your #2. Either we do it in * latex directly and output one big PDF which we can package separately so that it can be shipped on the livedvd and be updated as any other package, ( we could possibly add the release notes and the flyer in that package as well) * or in yelp as in #2.
If in #1, we choose latex, I would favour latex here too. What do you think ? "Design flows" is one of FEL's strengths. It would be difficult to push this upstream as many tools of different upstreams will fall in different flows. Hence we have to maintain it ourselves in our git. However we have to ensure it can also easily available so that other distributions can use that "Design flows" doc as reference.
Chitlesh
Hi,
--- On Sat, Dec 5, 2009 at 1:36 AM, Chitlesh GOORAH chitlesh@fedoraproject.org wrote: | I would tend to opt for LaTex as most of our upstream developers like | to keep their documentation in text format. --
We agree to use this for all our documentation needs.
--- | Having that said, what should we do for other tools which upstream | ships loads of documentation in OOo formats e.g kicad-doc ? --
If we can export the OOo formats to LaTeX directly or through intermediate formats like DocBook, we can maintain consistency.
--- | So here a decision should be made. If it was for me, pdf format is | enough. --
Agreed.
--- | Pointing to specific files would be great for the user, but hard on | us. Each time upstream add/remove docs, the packager will have to | update this yelp correctly. --
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.
This .guide file is important because it abstracts location of files from the GUI help manager, so we can use it across different desktop environments.
As long as it doesn't violate FHS, this will provide the user with available documentation. FESCo needs to look at it? Maybe, if we provide a prototype using FEL, we can get feedback and others' point of view? Just a thought.
--- | "Design flows" is one of FEL's strengths. It would be difficult to | push this upstream as many tools of different upstreams will fall in | different flows. Hence we have to maintain it ourselves in our git. --
Yes, we can maintain it as you have mentioned.
SK
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.
Hello
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 ?
Chitlesh
electronic-lab@lists.fedoraproject.org
-
Chitlesh GOORAH -
Shakthi Kannan