Pliant talk forum

Pliant talk forum

Discussion: About docs tree.

Propositions to simplify the new documentation tree.
Message posted by michel on 2002/04/17 17:26:53
Marcus, after Patrice's proposition of multilingual structure you have installed an
English documentation tree wich, in fact, is just the translation of the actual Pliant tree
with only the .page files.
The result, when installed is a dispersion of files and very long URL for cerain files.
Think that the same tres may be reproducted for each language with the same exact names 
for dircectories and principal files (not a translation).
I think it is possible to have a simplest way but you have to put in place all the tree
 for other contributors. 
I propose that the implantation of .page docs was 
"/pliantdocs/babel/lang/page_page/index.page" 
instead of now :                                  
"/pliantdocs/babel/lang/pliant/protocol/page.page"
Remind that the doc.style conduct to a greater number of files and practicaly to an excess directory.
Worse example exist: "/pliantdocs/babel/en/pliant/protocol/http/style/tiny.page" !!
What do you think of?
If you agree or after modification I"ll upload  af irst version of french .page doc at the end of the week.
Message posted by maybe Marcus on 2002/04/18 04:52:17
> I think it is possible to have a simplest way but you have to put in place all the tree
>  for other contributors. 
> I propose that the implantation of .page docs was 
> "/pliantdocs/babel/lang/page_page/index.page" 
> instead of now :                                  
> "/pliantdocs/babel/lang/pliant/protocol/page.page"

I think, for the time being, we should keep the tree structure of the
original Pliant documentation, i.e., the usual /pliant/(etc) under /pliantdocs/

The rationale is 
1) even though the URLs for the new documentation are longer, this actually is
not a problem, since it is unlikely that one will need to type URLs to go to
specific sites in the PDI. Patrice's constants uroot and nroot have proven quite
handy; specially if one day we decide to move things around. 

Later we may think about defining a more friendly navigation scheme (sth like 
what Patrice has done on his Pliant site), instead of the mundane "Back" or 
"Home" links
2)You mentioned:
> Remind that the doc.style conduct to a greater number of files and practicaly to an excess directory.
> Worse example exist: "/pliantdocs/babel/en/pliant/protocol/http/style/tiny.page" !!

The best way to solve that glitch is to change the path in the tiny.page file,
i.e., to 'module "/pliant/protocol/http/style/tiny.style"' instead of
module "tiny.style". 

I think we should keep the .style stuff where it is, i.e., in 
/pliant/pliant/protocol/http/style, since it closely relates to the Pliant
HTTP server.
3) If one day we decide to move everything back to the branch where the .pli stuff
is, since the tree structure is the same, we wouldn't have much problems to 
make this change (perhaps adding different endings to same documentation files
but different translations, e.g., if one day we have to put all documents of 
all languages perched on the same branch of the tree, then we will have sth like
index-fr.page, index-en.page, index-kr.page, etc.). 
4) I am now so used to the old tree structure, that it has become quite easy to 
find where things are in the tree (which now has a copy under 
/pliantdocs/babel/en/)

What do you guys think?
Message posted by maybe Marcus on 2002/04/18 11:39:12
More reasons for keeping the current documentation tree structure:

5) I am not sure if the following is easy to implement, but it would be nice 
to have this possibility: the idea is to have Pliant releases (the tar ball) in 
different languages available for downloading at the Pliant site, e.g., sth 
like pliant-74-fr.tgz or pliant-74-en.tgz.

To produce these tar balls, an automatic tool would gather the current 
documentation available on one particular language under the /pliantdocs/babel/
 branch and copy them over to the /pliant/ root (where the .pli stuff is). Then,
it would tar-compress the whole thing. Hence, we would end up with the same
original file tree structure, in which documentation and code share branches in 
the tree. (I really liked Hubert's original idea, and was kind of sad when 
realised that the new changes in the tree structure would separate code from doc.)

Therefore, in this idea, pliant/pliantdocs/(etc) would exist only as a site,
i.e., the Pliant release tar ball would contain all the documentation but in
one particular human language.

The advantages of this approach, I guess, are obvious.

Any thoughts?
up with a file tree in which  the firstvisits the Pliant site and wants to download the
pliant tar ball. The first thing that one has to choose is the (human) language
one wants the documentation. Then, an automatic tool would
Message posted by maybe Marcus on 2002/04/18 15:47:53
Please ignore the last three lines of my previous message.
Message posted by michel on 2002/04/18 20:46:52
Hi Marcus
Ok I'll follow your decision.
The most important is to have a common rule.