You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Upayavira <uv...@upaya.co.uk> on 2005/04/11 12:02:28 UTC
2.2 Documentation page naming
I've written a script that will convert old 2.1/2.2 documentation into
the proposed new format. However, because we're switching from a
hierarchical to a flat naming, we need a mapping between documents. I
have committed a document that shows my proposed mapping. Please
comment/correct/update. It can be found at:
http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/mapping-2.2.txt
This document also includes proposals for documentation to be simply
removed. Here's some observations:
1) The CTWIG docs aren't actually available on the site right now -
probably because there's no link to them, so the pages weren't
generated. As I understand it, they are very much 2.0 related, and we
need new tutorials of that nature. I therefore propose to remove this
from the 2.2 docs.
2) The FAQ section is COMPLETELY EMPTY! So lets remove it. We can always
add another should we wish to. At least there isn't any content to move
over!
3) The 'developing/dev guide section seems to relate to developing
webapps in 2.0. In 2.1/2.2, with CForms, flowscript, it is very
different. I propose to keep some of the info here, which is still
relevant, move the relevant portal docs into the portal block, and scrap
the rest - certainly the section will no longer exist.
4) Some content (e.g. tracks) would be easier to write from scratch,
conceiving exactly the docs we need, rather than trying to fit these
docs in somehow. I have therefore marked these as REMOVE.
Please follow the format I've used (comments in brackets, eg REMOVE),
filenames before the bracket, if any, as this is the format my script
expects.
<aside>
Having gone through this document, I can see the benefit of numeric URL
namespaces. Coming up with decent, consistent names, that don't clash,
is actually quite a tall order.
</aside>
Regards, Upayavira
Re: 2.2 Documentation page naming
Posted by Reinhard Poetz <re...@apache.org>.
Upayavira wrote:
> Reinhard Poetz wrote:
>
>> Upayavira wrote:
>>
>>> Definitely. I will take this approach and commit the docs to the live
>>> trunk docs repos with a prefix. Expect some big commits in the next
>>> couple of days!
>>>
>>> I'll prefix the blocks docs with c21-block-<blockname>, so that the
>>> docs survive before we can move them into another docs repository.
>>
>>
>>
>> The docs will go into
>> https://svn.apache.org/repos/asf/cocoon/trunk/src/documentation/src/content/xdocs/,
>> don't they?
>
>
> After Bertrand's suggestion, yes they will, with a c21- prefix.
fine
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
Re: 2.2 Documentation page naming
Posted by Upayavira <uv...@upaya.co.uk>.
Reinhard Poetz wrote:
> Upayavira wrote:
>
>> Definitely. I will take this approach and commit the docs to the live
>> trunk docs repos with a prefix. Expect some big commits in the next
>> couple of days!
>>
>> I'll prefix the blocks docs with c21-block-<blockname>, so that the
>> docs survive before we can move them into another docs repository.
>
>
> The docs will go into
> https://svn.apache.org/repos/asf/cocoon/trunk/src/documentation/src/content/xdocs/,
> don't they?
After Bertrand's suggestion, yes they will, with a c21- prefix.
Regards, Upayavira
Re: 2.2 Documentation page naming
Posted by Reinhard Poetz <re...@apache.org>.
Upayavira wrote:
> Definitely. I will take this approach and commit the docs to the live
> trunk docs repos with a prefix. Expect some big commits in the next
> couple of days!
>
> I'll prefix the blocks docs with c21-block-<blockname>, so that the docs
> survive before we can move them into another docs repository.
The docs will go into
https://svn.apache.org/repos/asf/cocoon/trunk/src/documentation/src/content/xdocs/,
don't they?
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
Re: 2.2 Documentation page naming
Posted by Upayavira <uv...@upaya.co.uk>.
Bertrand Delacretaz wrote:
> Le 11 avr. 05, à 12:02, Upayavira a écrit :
>
>> I've written a script that will convert old 2.1/2.2 documentation into
>> the proposed new format. However, because we're switching from a
>> hierarchical to a flat naming, we need a mapping between documents. I
>> have committed a document that shows my proposed mapping. Please
>> comment/correct/update....
>
> I haven't looked in detail yet, but it would be good to keep the "old
> path" information to have a traceable history of the move. If your
> script could add the old pathnames (like "developing/httprequest.html")
> to the meta.xml, for example, it might be useful.
That would be pretty easy.
> Also, are you planning to use the c21_ prefix convention for old docs?
> My idea with the move was to do it in two stages:
> a) move somedoc.html to c21_somedoc and add it to the "legacy" tab
> b) review c21_somedoc, and if we decide to keep it move it to somedoc or
> to a better name
Ah, I now see what you mean. I was planning to put the docs into a
different repository, and move them that way. You're proposing to put
them all into the new repository straight away, and just svn move the
files/folders as we work through them. That sounds reasonable enough.
> In this way, changes and decisions are traceable in SVN.
Yup.
> This also means that your name mappings are not terribly important at
> this stage, it's only in b) that the new name must be well chosen.
Definitely. I will take this approach and commit the docs to the live
trunk docs repos with a prefix. Expect some big commits in the next
couple of days!
I'll prefix the blocks docs with c21-block-<blockname>, so that the docs
survive before we can move them into another docs repository.
Regards, Upayavira
Re: 2.2 Documentation page naming
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 11 avr. 05, à 12:02, Upayavira a écrit :
> I've written a script that will convert old 2.1/2.2 documentation into
> the proposed new format. However, because we're switching from a
> hierarchical to a flat naming, we need a mapping between documents. I
> have committed a document that shows my proposed mapping. Please
> comment/correct/update....
I haven't looked in detail yet, but it would be good to keep the "old
path" information to have a traceable history of the move. If your
script could add the old pathnames (like "developing/httprequest.html")
to the meta.xml, for example, it might be useful.
Also, are you planning to use the c21_ prefix convention for old docs?
My idea with the move was to do it in two stages:
a) move somedoc.html to c21_somedoc and add it to the "legacy" tab
b) review c21_somedoc, and if we decide to keep it move it to somedoc
or to a better name
In this way, changes and decisions are traceable in SVN.
This also means that your name mappings are not terribly important at
this stage, it's only in b) that the new name must be well chosen.
-Bertrand