Non-root users can't install documentation / datasheets

[Rupert Swarbrick]

If I understand it correctly, documentation lookup is done using the gschemdoc.sh script. If a symbol has a documentation= attribute, this is used for searching. As explained at http://geda.seul.org/wiki/geda:master_attributes_list#documentation, if you give a filename for the documentation parameter on a symbol, the code looks in your local documentation directory. Unfortunately, on most linux systems this will be something like /usr/share/doc/geda-gaf.

If a non-root user wants to create symbols and link them to locally-downloaded datasheets, he or she is currently stuck. My suggestion is to add an environment variable - maybe GEDA_DOCDIRS - which can be set by the user. Have it colon-separated and check in these directories first.

I've coded up a version of gschemdoc.sh to do this and will attach it to the bug report as a patch. I've checked it with bash, ksh and dash: hopefully that's ok, but I'm not sure what else I need to check it with.

[Peter TB Brett (peter-b)]

Hi Rupert,

The git version of gschem doesn't use the gschemdoc shell script any more; the functionality has been ported to Scheme so it's usable on platforms without Bourne shells (i.e. Windows). http://git.geda-project.org/geda-gaf/tree/gschem/scheme/gschem/gschemdoc.scm

Your approach seems reasonable... but what about adding a user doc dir in the default search list? Something like:

1) If the environment variable is set, use that list of search paths;

2) Otherwise search in (a) a user doc directory and then (b) the system doc directory.

WDYT?

[Rupert Swarbrick (rswarbrick)]

Ah - since the file is still in the scripts directory, I assumed it was still used. What would be the path of the user doc directory in your option 2a though? I can't imagine that there's a sensible default - I mean, I wouldn't want to keep my store of datasheets in ~/.geda/ or the like.

Since this logic now done in scheme, we should also drop the environment variable idea. Customising it in gafrc files would be much nicer, I suspect. Shall I try to write a patch for gschemdoc.scm?

[Peter TB Brett (peter-b)]

Hi Rupert,

Sorry for taking so long to get back to you! I actually *do* suggest ~/.gEDA/ -- or rather, using the directory returned by (user-data-dir) somehow. See http://geda.peter-b.co.uk/geda-scheme/1.7.2/System-information.html

I still think that providing some way for non-root users to install documentation is a really good idea.

[Stephen Besch (sbesch)]

This is not exactly "Solved". While it is true that documentation files can be placed in /usr/local/share/doc/geda-gaf, to find this out, you actually have to place a scheme (write xxx) function in just the right place and run gschem from the command line. However, it still does not solve the problem of having all the component documentation in a system folder owned by root.

It is also not possible to simple add some code to gschemdoc.scm, since it does not have access to the needed info. You need to add a function or two to the API. I have done this and already published the code fixes for the current git head (as of 3-20-2013). I put this on the geda-users mailing list, but no-one seems to have cared enough to even respond. Here is the link, which contains a complete description of what I did and why. In brief, what it does is add the component's symbol directory to the search list. If it finds a directory named "documentation", then it searches it for the documentation file named in the documentation attribute.

Here is a link to the posting: http://www.delorie.com/archives/browse.cgi?p=geda-user/2013/03/17/17:02:33

[Peter TB Brett (peter-b)]

Stephen, your "fixes" broke API backwards compatibility, so nack. Also, the directory is a property of the library that the symbol representing the component was loaded from, not of the component object itself. Unfortunately we don't currently have a good scheme API for getting the underlying library of a symbol, nor for inspecting and manipulating the library configuration. I'm working on that, and once it's done I may revisit this issue.

In the meantime, I've modified gschemdoc to search a per-user documentation directory before the system documentation directory. The per-user documentation directory is currently $XDG_DATA_HOME/doc/geda-gaf. See commit 65a703ed3d36.

[Peter TB Brett (peter-b)]

See also bug 1293218.

[gpleda.org commit robot (gpleda-launchpad-robot)]

Bug was fixed by a commit
git master commit 65a703ed3d361ef9838da57f96910efe6a152c29
http://git.geda-project.org/geda-gaf/commit/?id=65a703ed3d361ef9838da57f96910efe6a152c29

commit 65a703ed3d361ef9838da57f96910efe6a152c29
Author: Peter TB Brett <email address hidden>
Commit: Peter TB Brett <email address hidden>

    gschemdoc: Search user-specific documentation directory.

    Enhance gschemdoc to search in $XDG_DATA_HOME/doc/geda-gaf (usually
    $HOME/.local/share/doc/geda-gaf) before looking in the system
    documentation directory.

    Closes-bug: lp-971585

[Stephen Besch (sbesch)]

Peter,

The real problem is that Component documentation is still broken! Having all documentation in one massive folder - even if it is in the user's home directory - just does not cut it. I am also curious to know exactly how I "BROKE: api backwards compatibility?? I was absolutely fastidious about NOT removing or changing anything that was already in the code in any way that would make existing code break - even if it appeared to NOT ever be used. Did you just assume that adding a function to fetch the symbol's folder of residence would break the API? Did you actually TEST it. Are you sure that It didn't break FORWARD compatibility??

The problem for me now is that I just updated and recompiled the latest git release and discovered that all of my documentation requests are again bumping out the the WEB and ignoring all local documents. I still believe that the only rational way to handle the Documentation issue is to put them into the same folder as the symbol itself.

Now I am left with re-applying my own modifications and running a personal - patched - version which will get creamed every time I update. Thanks

Stephen R Besch