[ptxdist] [PATCH] README: update

[ptxdist] [PATCH] README: update

[Roland Hieber]

When reading this README, the tarball was obviously already extracted,
so remove the very unclear section about how to get it. Anyway, anything
important is in the manual, which is linked later.

TODO is no longer there since commit b710f8cdf410a91b4298 ("PTXdist:
remove useless and unmaintained files").

Link to the new documentation directly instead of through a redirected
URL, and fix incorrect use of "refer" in the section heading.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 README | 20 +++++---------------
 1 file changed, 5 insertions(+), 15 deletions(-)

diff --git a/README b/README
index 33cf90e0bc19..608b4749bdcd 100644
--- a/README
+++ b/README
@@ -1,15 +1,6 @@
 PTXdist
 =======
 
-Necessary Packages
-------------------
-
-In order to build ptxdist, you need this archive:
-
-	ptxdist-<version>.tgz
-
-Extract this archive into some build directory.
-
 Installation
 ------------
 
@@ -107,15 +98,14 @@ Bugs
 ----
 
 - search for FIXMEs
-- see TODO
 
-For documentation please refer:
--------------------------------
+For documentation please refer to:
+----------------------------------
 
-http://www.pengutronix.de/software/ptxdist/documentation_en.html
+https://www.ptxdist.org/doc
 
-For Patch Tagging please refer:
--------------------------------
+For Patch Tagging please refer to:
+----------------------------------
 
 http://dep.debian.net/deps/dep3/
 
-- 
2.23.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH] README: update

[Michael Tretter]

On Sun, 01 Sep 2019 23:04:56 +0200, Roland Hieber wrote:
> When reading this README, the tarball was obviously already extracted,
> so remove the very unclear section about how to get it. Anyway, anything
> important is in the manual, which is linked later.

I agree that the section is unclear, but the README can be read from
the git webview, too. Maybe this section should be rewritten for the
viewpoint of a git user?

Michael

> 
> TODO is no longer there since commit b710f8cdf410a91b4298 ("PTXdist:
> remove useless and unmaintained files").
> 
> Link to the new documentation directly instead of through a redirected
> URL, and fix incorrect use of "refer" in the section heading.
> 
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> ---
>  README | 20 +++++---------------
>  1 file changed, 5 insertions(+), 15 deletions(-)
> 
> diff --git a/README b/README
> index 33cf90e0bc19..608b4749bdcd 100644
> --- a/README
> +++ b/README
> @@ -1,15 +1,6 @@
>  PTXdist
>  =======
>  
> -Necessary Packages
> -------------------
> -
> -In order to build ptxdist, you need this archive:
> -
> -	ptxdist-<version>.tgz
> -
> -Extract this archive into some build directory.
> -
>  Installation
>  ------------
>  
> @@ -107,15 +98,14 @@ Bugs
>  ----
>  
>  - search for FIXMEs
> -- see TODO
>  
> -For documentation please refer:
> --------------------------------
> +For documentation please refer to:
> +----------------------------------
>  
> -http://www.pengutronix.de/software/ptxdist/documentation_en.html
> +https://www.ptxdist.org/doc
>  
> -For Patch Tagging please refer:
> --------------------------------
> +For Patch Tagging please refer to:
> +----------------------------------
>  
>  http://dep.debian.net/deps/dep3/
>  

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH] README: update

[Michael Olbrich]

On Mon, Sep 02, 2019 at 10:23:40AM +0200, Michael Tretter wrote:
> On Sun, 01 Sep 2019 23:04:56 +0200, Roland Hieber wrote:
> > When reading this README, the tarball was obviously already extracted,
> > so remove the very unclear section about how to get it. Anyway, anything
> > important is in the manual, which is linked later.
> 
> I agree that the section is unclear, but the README can be read from
> the git webview, too. Maybe this section should be rewritten for the
> viewpoint of a git user?

I think it can be removed. This section used to contain multiple archives
that had to be downloaded but all others are gone now.

> > 
> > TODO is no longer there since commit b710f8cdf410a91b4298 ("PTXdist:
> > remove useless and unmaintained files").
> > 
> > Link to the new documentation directly instead of through a redirected
> > URL, and fix incorrect use of "refer" in the section heading.
> > 
> > Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> > ---
> >  README | 20 +++++---------------
> >  1 file changed, 5 insertions(+), 15 deletions(-)
> > 
> > diff --git a/README b/README
> > index 33cf90e0bc19..608b4749bdcd 100644
> > --- a/README
> > +++ b/README
> > @@ -1,15 +1,6 @@
> >  PTXdist
> >  =======
> >  
> > -Necessary Packages
> > -------------------
> > -
> > -In order to build ptxdist, you need this archive:
> > -
> > -	ptxdist-<version>.tgz
> > -
> > -Extract this archive into some build directory.
> > -
> >  Installation
> >  ------------
> >  
> > @@ -107,15 +98,14 @@ Bugs
> >  ----
> >  
> >  - search for FIXMEs
> > -- see TODO
> >  
> > -For documentation please refer:
> > --------------------------------
> > +For documentation please refer to:
> > +----------------------------------
> >  
> > -http://www.pengutronix.de/software/ptxdist/documentation_en.html
> > +https://www.ptxdist.org/doc
> >  
> > -For Patch Tagging please refer:
> > --------------------------------
> > +For Patch Tagging please refer to:
> > +----------------------------------
> >  
> >  http://dep.debian.net/deps/dep3/
> >  

I think this part should be removed. We don't do it like this anyways and
either way, the README is not the place for this.

Michael

> 
> _______________________________________________
> ptxdist mailing list
> ptxdist@pengutronix.de
> 

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH] README: update

[Ladislav Michl]

On Mon, Sep 02, 2019 at 11:09:49AM +0200, Michael Olbrich wrote:
> On Mon, Sep 02, 2019 at 10:23:40AM +0200, Michael Tretter wrote:
> > On Sun, 01 Sep 2019 23:04:56 +0200, Roland Hieber wrote:
[...]
> > > @@ -107,15 +98,14 @@ Bugs
> > >  ----
> > >  
> > >  - search for FIXMEs
> > > -- see TODO
> > >  
> > > -For documentation please refer:
> > > --------------------------------
> > > +For documentation please refer to:
> > > +----------------------------------
> > >  
> > > -http://www.pengutronix.de/software/ptxdist/documentation_en.html
> > > +https://www.ptxdist.org/doc
> > >  
> > > -For Patch Tagging please refer:
> > > --------------------------------
> > > +For Patch Tagging please refer to:
> > > +----------------------------------
> > >  
> > >  http://dep.debian.net/deps/dep3/
> > >  
> 
> I think this part should be removed. We don't do it like this anyways and
> either way, the README is not the place for this.

So now it seems README would contain mostly instalation instructions. What
about moving them into INSTALL, rename README.devel to README and be done
with that? :)

	ladis

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH] README: update

[Roland Hieber]

On Mon, Sep 02, 2019 at 01:36:35PM +0200, Ladislav Michl wrote:
> On Mon, Sep 02, 2019 at 11:09:49AM +0200, Michael Olbrich wrote:
> > On Mon, Sep 02, 2019 at 10:23:40AM +0200, Michael Tretter wrote:
> > > On Sun, 01 Sep 2019 23:04:56 +0200, Roland Hieber wrote:
> [...]
> > > > @@ -107,15 +98,14 @@ Bugs
> > > >  ----
> > > >  
> > > >  - search for FIXMEs
> > > > -- see TODO
> > > >  
> > > > -For documentation please refer:
> > > > --------------------------------
> > > > +For documentation please refer to:
> > > > +----------------------------------
> > > >  
> > > > -http://www.pengutronix.de/software/ptxdist/documentation_en.html
> > > > +https://www.ptxdist.org/doc
> > > >  
> > > > -For Patch Tagging please refer:
> > > > --------------------------------
> > > > +For Patch Tagging please refer to:
> > > > +----------------------------------
> > > >  
> > > >  http://dep.debian.net/deps/dep3/
> > > >  
> > 
> > I think this part should be removed. We don't do it like this anyways and
> > either way, the README is not the place for this.
> 
> So now it seems README would contain mostly instalation instructions. What
> about moving them into INSTALL, rename README.devel to README and be done
> with that? :)

No, I'd rather keep the README as a short intro for new users without
any clue about PTXdist, so they can find out quickly if they want to
invest more time in it. All the developer-related stuff is already in
the documentation, we can remove it here and link to the docs.

-- 
Roland Hieber                     | r.hieber@pengutronix.de     |
Pengutronix e.K.                  | https://www.pengutronix.de/ |
Peiner Str. 6-8, 31137 Hildesheim | Phone: +49-5121-206917-5086 |
Amtsgericht Hildesheim, HRA 2686  | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

[ptxdist] [PATCH v2] README: update

[Roland Hieber]

Remove the unclear "Necessary Packages" section, when reading this
README, the sources are obviously already available.

Add links to the web documentation, which also contains all relevant
info about directory structure, quickstart, patching, etc. Keep the
overall idea as a very short intro for new users.

Apply copy editing and very small improvements in the "Idea" section.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 README | 91 +++++++++-------------------------------------------------
 1 file changed, 13 insertions(+), 78 deletions(-)

diff --git a/README b/README
index 33cf90e0bc19..86e111c1754e 100644
--- a/README
+++ b/README
@@ -1,15 +1,6 @@
 PTXdist
 =======
 
-Necessary Packages
-------------------
-
-In order to build ptxdist, you need this archive:
-
-	ptxdist-<version>.tgz
-
-Extract this archive into some build directory.
-
 Installation
 ------------
 
@@ -33,89 +24,33 @@ For developers who want to work with git versions of PTXdist it is only
 necessary to run "./autogen.sh && ./configure && make" and set the PATH
 variable to the bin/ directory inside the PTXdist tree.
 
-
-Quickstart
-----------
-
-Read the "How to become a PTXdist Guru" guide to get an idea how PTXdist works.
-This document can be found here:
-
-http://www.pengutronix.de/software/ptxdist/appnotes/OSELAS.BSP-Pengutronix-Generic-arm-Quickstart.pdf
-
-
 Idea
 ----
 
-PTXdist is a tool which can be used to generate a root tree for all
-kinds of Linux systems. It was written with embedded systems in mind,
-but there is no reason why you can't use it to configure your firewall,
-router or whatever dedicated "device" comes to your mind.
+PTXdist is a build system which can be used to generate a root tree and
+disk images for all kinds of Linux systems. It was written with embedded
+systems in mind, but there is no reason why you can't use it to
+configure your firewall, router or whatever dedicated "device" comes to
+your mind.
 
 The job works like this: you run 'ptxdist menuconfig' and
-"ptxdist platformconfig", configure what you need. Run 'ptxdist go'
-and you'll find a root tree in <you-platform>/root/. Voila.
+'ptxdist platformconfig', configure what you need. Run 'ptxdist images'
+and you'll find a root tree in ./platform-<name>/root/, and disk images
+in ./platform-<name>/images/. Voilà.
 
 All magic necessary to do these things in a cross enviroment are written
 into "recipies", living in rules/*.make, and config menues in
 rules/*.in.
 
+Documentation
+-------------
 
-Directory Layout
-----------------
-
-These files and directories are supposed to be in an empty project
-directory:
-
-configs/		project specific configurations (optional)
-patches/		project specific patches, overwrites the generic
-			ones from PTXdist
-projectroot/		put files here which are to be copied over to
-			the target's root directory, like for example
-			etc files, scripts, ... Note that the copying
-			has to be done explicitly by some project
-			specific rule file.
-ptxconfig		.config file to configure the userland for
-			your project.
-platformconfig		.config file to configure the platform specific
-			part of your project.
-rules/			contains project specific rules
-src -> ...		link to point to your directory containing
-			tarball files for the packets.
-
-Additionally some other directories are being built when you run
-"ptxdist go" or other start other build targets.
-
-<platform>/build-host/	build directory for host tools
-<platform>/build-cross/	build directory for cross tools
-<platform>/build-target/ build directory for target tools
-<platform>/images/	'ptxdist images' creates tarballs and
-			filesystem images in this directory.
-<platform>/sysroot-target/ target related libs and headerfiles are going to
-			this dir
-<platform>/sysroot-cross/ target related tools, but must run on host are
-			going to this dir
-<platform>/sysroot-host/ host related tools are going to this dir
-
-<platform>/root/	root filesystem for the target
-<platform>/state/	state files (show in which state packages
-			currently are during the compilation)
-
-For more details look at the output of 'ptxdist --help' or see the
-PTXdist manual.
+See <https://www.ptxdist.org/doc/> for the full documentation, which
+includes a quickstart guide as well as a reference for users and
+developers.
 
 Bugs
 ----
 
 - search for FIXMEs
 - see TODO
-
-For documentation please refer:
--------------------------------
-
-http://www.pengutronix.de/software/ptxdist/documentation_en.html
-
-For Patch Tagging please refer:
--------------------------------
-
-http://dep.debian.net/deps/dep3/
-
-- 
2.23.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de