[dev] documentation folder for applications

[Jan Schneider]

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.

> ?) Not sure what to do with documentation cross-links.

See above.

Jan.

-- 
Do you need professional PHP or Horde consulting?
http://horde.org/consulting/