[dev] documentation folder for applications

[Vilius Šumskas]

> Zitat von Vilius ?umskas <vilius at lnk.lt>:
> 
> > Gunnar Wrobel <wrobel at horde.org> ra??:
> >
> >> Quoting Ralf Lang <lang at b1-systems.de>:
> >>
> >>> Am Freitag, 1. Juli 2011, 17:11:27 schrieb Jan Schneider:
> >>>> Zitat von Vilius ?umskas <vilius at lnk.lt>:
> >>>>> Hi,
> >>>>>
> >>>>> I've noticed that most released applications install their
> >>>>> documentation into /usr/share/pear/doc. Is there another good
> reason
> >>>>> for this except that "all PEAR packages install documentation into
> >>>>> pear/doc"? I can justify why this is OK for libraries, but in my
> >>>>> opinion INSTALL/UPGRADING documentation for applications should
> be
> >>>>> installed into application root folder. Because it is really
> >>>>> uncommon for the administrators to find documentation in
> >>>>> /usr/share/pear/doc. Especially for administrators of web
> >>>>> applications (even if they are distrubuted through PEAR).
> >>>>
> >>>> Good question. Policy-wise they should be using the docs role and thus
> >>>> being installed to PEAR's doc folder. But I could see us ignoring that
> >>>> and using the horde role instead, if that is consensus.
> >>>>
> >>>> Jan.
> >>>
> >>> Actually, when packaging for distribution I change the doc_dir value to
> the
> >>> system's doc path. Docs are ending up where the docs of rpm packages
> are
> >>> expected to be.
> >>>
> >>> I see it reasonable to have a pear package's docs where pear
> >>> package docs are
> >>> expected, too.
> >>>
> >>> As I understand the horde role, it's mainly a role for
> >>> web-accessible parts,
> >>> right?
> >>>
> >>> I see no need to have docs in a web-accessible dir (and possible
> reverting
> >>> this with a .htaccess file)
> >>
> >> Same here. Docs should be "doc" role to allow clean separation of
> >> files depending on - well - their role and there is no specific
> >> reasons why those should be web-accessible.
> >>
> >> The install location can of course also be tweaked during the
> >> installation which we could mention in the install instructions.
> >
> > I agree that there is no point to make docs web-accessible, but they
> > should be easier to find. As I said, web application administrators
> > are still used to search for documentation in www root. Moreover,
> > currently various Horde places points to the folder which doesn't
> > exist. For example:
> >
> > "The test script is currently enabled. For security reasons, disable
> > test scripts when you are done testing (see horde/docs/INSTALL)."
> >
> > Documentation cross-links doesn't work too.
> >
> > Also, currently some documentation files like README and COPYING are
> > located in the application's root, but installed into "data" role
> > for some reason. I suppose this is because of Chora, but maybe it
> > makes sense to change Chora so it can show README from /docs/ too?
> >
> >> What might be nice though would be a post installation script that
> >> just spits out the directory names that received horde files. Not
> >> certain though if this is easily feasible so that it always happens
> >> as the last action after an installation (whether it might be a
> >> single application installation of the installation of a bundle).
> >
> > Could be a solution. But only if this is implemented sooner not
> > later. IMHO easy documentation for open source project should be one
> > of the biggest priorities, so new users can easily install/upgrade
> > and help themselves. And by doing so increase user base and the
> > amount of coming-in patches of course :)
> >
> > Considering the above will be implemented I propose the following
> structure:
> > a) All documentation should reside in /application/docs folder in
> > Git, including README and COPYING.
> 
> I think we should keep README in the base dir, so it's visible
> immediately when looking into an app's folder. It should use the doc
> role though.
> 
> > b) All documentation should be installed under PEAR's doc role.
> > c) All references in Horde interface should be updated to point to
> > real folder. Probably can get it from include_path? Or maybe linked
> > to the website?
> 
> This is not possible because they are static files. The doc_dir
> setting can be different from system to system too. I only see a
> viable option to not use any paths at all when referencing to those
> files.
> On the website all files are already linked correctly.

Or maybe something like?

"The test script is currently enabled. For security reasons, disable test scripts when you are done testing (see horde/INSTALL in PEAR's documentation folder)".

But then again, at least for me it sounds like we are adding more problems here just because of  PEAR wide policy.

-- 
  Vilius