* [U-Boot] organizing doc/ dir?
2011-02-23 6:02 [U-Boot] organizing doc/ dir? Kumar Gala
@ 2011-02-23 6:19 ` Wolfgang Denk
2011-02-23 6:26 ` Peter Tyser
2011-02-23 6:36 ` Albert ARIBAUD
2 siblings, 0 replies; 4+ messages in thread
From: Wolfgang Denk @ 2011-02-23 6:19 UTC (permalink / raw)
To: u-boot
Dear Kumar Gala,
In message <78B99ACF-EC73-4DBC-B4EE-49F1B33B9501@kernel.crashing.org> you wrote:
>
> Any issue that added a little hierarchy to the doc/ dir?
Excellent idea - thanks!
> maybe something mimic board/
>
> for example:
>
> doc/README.mpc8313erdb -> doc/freescale/README.mpc8313erdb
> doc/README.mpc8315erdb -> doc/freescale/README.mpc8315erdb
> doc/README.mpc8323erdb -> doc/freescale/README.mpc8323erdb
> doc/README.mpc832xemds -> doc/freescale/README.mpc832xemds
> doc/README.mpc8349itx -> doc/freescale/README.mpc8349itx
> doc/README.mpc8360emds -> doc/freescale/README.mpc8360emds
> doc/README.mpc837xemds -> doc/freescale/README.mpc837xemds
> doc/README.mpc837xerdb -> doc/freescale/README.mpc837xerdb
> doc/README.mpc83xxads -> doc/freescale/README.mpc83xxads
> doc/README.mpc83xx.ddrecc-> doc/freescale/README.mpc83xx.ddrecc
...
Eventually we should folow the code layout and do
doc/board/freescale/README.mpc8313erdb
doc/board/freescale/README.mpc8315erdb
doc/board/freescale/README.mpc8323erdb
doc/board/freescale/README.mpc832xemds
....
but
README.mpc83xx.ddrecc
is not specific to Freescale boards and should be somewhere else.
Best regards,
Wolfgang Denk
--
DENX Software Engineering GmbH, MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Remember, there's a big difference between kneeling down and bending
over. - Frank Zappa
^ permalink raw reply [flat|nested] 4+ messages in thread
* [U-Boot] organizing doc/ dir?
2011-02-23 6:02 [U-Boot] organizing doc/ dir? Kumar Gala
2011-02-23 6:19 ` Wolfgang Denk
@ 2011-02-23 6:26 ` Peter Tyser
2011-02-23 6:36 ` Albert ARIBAUD
2 siblings, 0 replies; 4+ messages in thread
From: Peter Tyser @ 2011-02-23 6:26 UTC (permalink / raw)
To: u-boot
On Wed, 2011-02-23 at 00:02 -0600, Kumar Gala wrote:
> Wolfgang,
>
> Any issue that added a little hierarchy to the doc/ dir?
>
> maybe something mimic board/
>
> for example:
>
> doc/README.mpc8313erdb -> doc/freescale/README.mpc8313erdb
> doc/README.mpc8315erdb -> doc/freescale/README.mpc8315erdb
> doc/README.mpc8323erdb -> doc/freescale/README.mpc8323erdb
> doc/README.mpc832xemds -> doc/freescale/README.mpc832xemds
> doc/README.mpc8349itx -> doc/freescale/README.mpc8349itx
> doc/README.mpc8360emds -> doc/freescale/README.mpc8360emds
> doc/README.mpc837xemds -> doc/freescale/README.mpc837xemds
> doc/README.mpc837xerdb -> doc/freescale/README.mpc837xerdb
> doc/README.mpc83xxads -> doc/freescale/README.mpc83xxads
> doc/README.mpc83xx.ddrecc-> doc/freescale/README.mpc83xx.ddrecc
> doc/README.mpc8536ds -> doc/freescale/README.mpc8536ds
> doc/README.mpc8544ds -> doc/freescale/README.mpc8544ds
> doc/README.mpc8569mds -> doc/freescale/README.mpc8569mds
> doc/README.mpc8572ds -> doc/freescale/README.mpc8572ds
> doc/README.mpc85xxads -> doc/freescale/README.mpc85xxads
> doc/README.mpc85xxcds -> doc/freescale/README.mpc85xxcds
> doc/README.mpc8610hpcd -> doc/freescale/README.mpc8610hpcd
> doc/README.mpc8641hpcn -> doc/freescale/README.mpc8641hpcn
What about adding a doc/board directory? eg:
doc/README.mpc8313erdb -> doc/board/freescale/README.mpc8313erdb
doc/README.mpc8315erdb -> doc/board/freescale/README.mpc8315erdb
doc/README.ocotea -> doc/board/amcc/README.ocotea
doc/README.ebony -> doc/board/amcc/README.ebony
doc/README.zeus -> doc/board/README.zeus
doc/README.xpedite1k -> doc/board/README.xpedite1k
Since the majority of documentation is board specific at this point,
it'd be nice if it was all moved into a subdirectory to clean up the
top-level doc/ dir.
Also, without the board subdirectory it'd be unclear where general
Freescale documentation that was relevant to multiple board vendors
would go. Eg README.fsl-ddr - doc/freescale? or doc/?.
A reorganization sounds nice either way!
Peter
^ permalink raw reply [flat|nested] 4+ messages in thread
* [U-Boot] organizing doc/ dir?
2011-02-23 6:02 [U-Boot] organizing doc/ dir? Kumar Gala
2011-02-23 6:19 ` Wolfgang Denk
2011-02-23 6:26 ` Peter Tyser
@ 2011-02-23 6:36 ` Albert ARIBAUD
2 siblings, 0 replies; 4+ messages in thread
From: Albert ARIBAUD @ 2011-02-23 6:36 UTC (permalink / raw)
To: u-boot
Hi Kumar and others,
Le 23/02/2011 07:02, Kumar Gala a ?crit :
> Wolfgang,
>
> Any issue that added a little hierarchy to the doc/ dir?
>
> maybe something mimic board/
I would tend to agree wholeheartedly to the idea, if only because /doc
currently contains 154 files, which meakes it not that easy to sort
things out.
But why limit oneself to boards? U-Boot has a structured arch/ dir as
well, and lib/ also, to name only some. Structuring /doc after these as
well would be quite useful as:
- only general U-Boot doc files would reside directly under /doc, making
it easier for beginners to grasp U-boot essentials (and for seasoned
users to brush up their knowledge) -- for instance, the rationales for
U-Boot such as the recently discussed float issue could be made much
more visible by being one of a few files in /doc itself;
- arch-related files under /doc/arch (including a rationale file
explaining how /arch itself is organized) and arch-specific files under
/doc/arch/<arch> -- /doc/arch/arm would hold all ARM related stuff; that
would make arch, cpu, SoC specific information easier to locate;
- lib-related files in /doc/lib to better explain and document the "as
much of libc behavior as needed but no more" approach;
- possibly even on a far further future, automated doc generation from
code annotations would help keeping the doc up-to-date and benefit from
/doc mimicking the source code tree structure -- but granted, it may not
be that easy to find where in the code some of what /doc contains now
should go.
... and I'm certainly missing other benefits.
So yes, I would second a /doc reorg beyond a mere /doc/boards creation.
Amicalement,
--
Albert.
^ permalink raw reply [flat|nested] 4+ messages in thread