Re: [documancer] Re: [documancer-users] a few bugs?

[<arn...@we...>]

Hi Vaclav,

On Thu, 11 Dec 2003, Vaclav Slavik wrote:

> Hi,
>
> (sorry for late reply, I was away during the weekend and was a bit
> busy ever since)

same with me, just to much to be done before christmas ;-),
but here we go ...

> > c) For pydoc: site-packages/wxPython/wx:
> >     either: crashes
> >     or: mouse pointer with watch - application hangs
> >
> >     However, other texts work, so this might be caused by wx ?
>
> Rather by the way pydoc works -- it imports the modules and this may
> cause problems if the module does some initialization immediately
> when imported. The only safe fix seems to be to abandon pydoc and use
> epydoc or HappyDoc to generate documentation from Python sources.
> That or running pydoc in separate process.

epydoc or HappyDoc might be worth a try

Thanks for the fixes!

And now to a couple of further points:

- Place of the installed documancer:
  When installing from CVS I did
    export PHOME=${HOME}/PYTHON_TST/
    ./autogen.sh
    ./configure --prefix=${PHOME}
    make
    make install

  The documancer files were put in
    ${HOME}/PYTHON_TST/lib/documancer
  where I would have expected them to be in
    ${HOME}/PYTHON_TST/lib/python2.3/site-packages/documancer

  (Actually, a setup.py file might be nice).

- Books manager:
  starting afresh (i.e. no books added yet)
  I first entered a Book title, selected Html
  but did not get the URL field.
  Only then I realized that I have to press "New" first
  and only then one can add the book.
  Ok, this is user stupidity ;-), but maybe one should either
    a) disable the entry fields first
    b) or allow for adding a book
      by just typing the information
      and accept this by pressing
      an "Add" button.

  Also by pressing "New" a "book's name"
  entry box opens even though there
  is entry field for this
  (Named "Book title" vs. "book's name").
  To summarize: I think it would be more intuitive
  to go for variant b).

- after adding the first book and returning from the Books manager
  the index page of this document is not shown.
  (One has to press "Return to homepage" explicitly).

- when doing a search the first hit could be shown
  automatically (maybe as option)
  (also the width of "Score" and "Document" is not
   well adapted and changing the width of the Search/Bookmarks
   part the widths of "Score"/"Documents" is not changed accordingly)
- clicking on a result after a search opens
  the page of that document, but does not jump to
  the position of the first hit in that document
- after a search: buttons (and key shortcuts)
  to move to the next/previous hit in the document
- searches across several books would be useful as well
  (e.g. with a tick-list to specify which
   books should be included in the search)
- it would be nice if updating/generating an index is
  done in a separate thread (+ a busy indicator maybe ...).
  (Then one could at least continue browsing in the meantime ...)
- When clicking on a link to a ps or pdf document
  there is always a kind of download window,
  titled wxmozilla. It contains a list of all the
  previous .ps/.pdf.
  Is there a way to (optionally)
  prevent this window from showing up at all?
  (even though it might be sometimes nice as it allows to inspect
   the settings for wxmozilla with about:config)
- "About": you could include a link to the web-page
  (so interested users can get straight to all further information,
   e.g. mailing list, updates etc. ...)


Wish-List points:
- Support for a tree view of Table of Contents for the books
  a la wxHtmlHelper, like e.g. for the wxpython doku.

  I.e. this would mean support for the .hhp files
  (from the.hhc/.hhk/.hhp combo)

  ((Actually, I think that will be the last open point
  to make me switch from helpviewer.py to documancer ;-))

Some meta stuff (not thought to an end ;-):
- I am thinking of using documancer as _the_ documentation
  center for our course on computational physics next summer term.
  So there will be several users accessing the same base of documents
  (python documentation, dive-into-python tutorial, Numeric manual,
  scipy documentation, wxPython manual, ...).
  Therefore it would be nice to have the search indices
  for these documents just generated once (by "root")
  so that the users to not have to create and store
  their own copy of this.

- In addition to html files there might be also pdf files.
  Would it be possible to include these into the search
  when they are referenced from a html file?

  This might open a can of worms - I.e.,
  if one allows for external files how could documancer
  know that a rebuilt of the search index is
  necessary if any of the files has changed?

- Thinking of having a documancer session open all the time
  it would be nice if there is a way to
  direct queries from an interactive (I)python session
  (or pycrust, or emacs, or ...)
  to documancer.

OK, enough for this time,

Arnd