Documentation/User Manual questions

Documentation/User Manual questions

[Theodore A. Roth]

Hi,

In my quest to learn how OE works, I've been reading the Wiki and the
User Manual a lot. I have a few questions to ask.

1: Why is the user manual on a separate branch instead of simply being
part of the org.openembedded.dev branch?

Speaking as a newbie, it would have been nice to have gotten the user
manual automagically when I cloned the git repo. It took me a couple
of weeks to discover where it's source was located since I am also
learning git at the same time. Speaking as developer, having the
documentation as close to the source as possible gives it more
visibility and tends to increase the likelihood of it being kept up to
date.

2: Was the documentation branch really last updated on May 9, 2008? Is
there a newer branch I have not yet discovered?

3: There is a ton of information in the Wiki, but finding what one
needs can be rather tedious if not difficult. Is there any chance of
pulling information from the Wiki into the user manual?

The format of a user manual can make finding information so much more
efficient. A table of contents and a good index can make a newbies
life so much easier.

I would love to step up and take on some of this. My knowledge of OE
is quite limited at the moment, but with some review from the gurus
out there, I think I can remedy that.

Thanks for your time.

Ted Roth

Re: Documentation/User Manual questions

[Cliff Brake]

On Fri, Feb 20, 2009 at 9:18 PM, Theodore A. Roth <taroth@gmail.com> wrote:

> 2: Was the documentation branch really last updated on May 9, 2008? Is
> there a newer branch I have not yet discovered?

Yes, this is likely correct.  Documentation is not OE's strong point.
But the combination of various docs available cover things pretty
well:

http://wiki.openembedded.net/index.php/Documentation

Assistance with documentation is welcome :-)

> 3: There is a ton of information in the Wiki, but finding what one
> needs can be rather tedious if not difficult. Is there any chance of
> pulling information from the Wiki into the user manual?
>
> The format of a user manual can make finding information so much more
> efficient. A table of contents and a good index can make a newbies
> life so much easier.
>
> I would love to step up and take on some of this. My knowledge of OE
> is quite limited at the moment, but with some review from the gurus
> out there, I think I can remedy that.

I would be happy to review patches.

Thanks,
Cliff

-- 
=======================
Cliff Brake
http://bec-systems.com

RFC: Importing docs directory to org.oe.dev.

[Michael 'Mickey' Lauer]

I want to propose importing the documentation into the org.oe.dev
branch, notably in the docs directly.

Toss your votes.
	
-- 
:M:

Re: RFC: Importing docs directory to org.oe.dev.

[Michael 'Mickey' Lauer]

Am Dienstag, den 24.02.2009, 17:14 +0100 schrieb Michael 'Mickey' Lauer:
> I want to propose importing the documentation into the org.oe.dev
> branch, notably in the docs directly.

s/directly/directory/.

-- 
:M:

Re: RFC: Importing docs directory to org.oe.dev.

[Cliff Brake]

On Tue, Feb 24, 2009 at 11:14 AM, Michael 'Mickey' Lauer
<mlauer@vanille-media.de> wrote:
> I want to propose importing the documentation into the org.oe.dev
> branch, notably in the docs directly.

Sounds good to me.  It is a minuscule amount of data -- no reason to
have it separate.

Thanks,
Cliff

-- 
=======================
Cliff Brake
http://bec-systems.com

Re: RFC: Importing docs directory to org.oe.dev.

[Koen Kooi]

On 24-02-09 17:37, Cliff Brake wrote:
> On Tue, Feb 24, 2009 at 11:14 AM, Michael 'Mickey' Lauer
> <mlauer@vanille-media.de>  wrote:
>> I want to propose importing the documentation into the org.oe.dev
>> branch, notably in the docs directly.
>
> Sounds good to me.  It is a minuscule amount of data -- no reason to
> have it separate.

It was kept seperate to allow docs write access to the docs, but not to 
the main repository. If we are OK with given docs writes global access, 
please import the docs.
Personally I dislike having a 200MB git repo for a few kiB of docs, but 
then again, my 1TB disk just arrived :)

regards,

Koen

Re: RFC: Importing docs directory to org.oe.dev.

[Martyn Welch]

Michael 'Mickey' Lauer wrote:
> I want to propose importing the documentation into the org.oe.dev
> branch, notably in the docs directly.
> 

This is a very sensible suggestion - the docs should reflect the branch in which that exist, the docs for the stable branch will by necessity need to be different from those of devel at times. An example would be the change from ipkg to opkg.

Martyn

-- 
Martyn Welch MEng MPhil MIET (Principal Software Engineer)   T:+44(0)1327322748
GE Fanuc Intelligent Platforms Ltd,        |Registered in England and Wales
Tove Valley Business Park, Towcester,      |(3828642) at 100 Barbirolli Square,
Northants, NN12 6PF, UK T:+44(0)1327359444 |Manchester,M2 3AB  VAT:GB 729849476

Re: RFC: Importing docs directory to org.oe.dev.

[Michael 'Mickey' Lauer]

It's done now and we can start applying the patches that came to improve
the docs.

Cheers,

-- 
:M:

Re: Documentation/User Manual questions

[Philip Balister]

[-- Attachment #1: Type: text/plain, Size: 682 bytes --]

Cliff Brake wrote:
> On Fri, Feb 20, 2009 at 9:18 PM, Theodore A. Roth <taroth@gmail.com> wrote:
> 
>> 2: Was the documentation branch really last updated on May 9, 2008? Is
>> there a newer branch I have not yet discovered?
> 
> Yes, this is likely correct.  Documentation is not OE's strong point.
> But the combination of various docs available cover things pretty
> well:
> 
> http://wiki.openembedded.net/index.php/Documentation

I notice you keep copies of the manual on your website. Last week Koen 
suggested we add docs.openembedded.org to DNS. Would it make sense to go 
ahead and add this address and use it for "static" copies of documentation?

Philip

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/x-pkcs7-signature, Size: 3303 bytes --]

Re: Documentation/User Manual questions

[Cliff Brake]

On Wed, Feb 25, 2009 at 9:48 AM, Philip Balister <philip@balister.org> wrote:
> Cliff Brake wrote:
>>
>> On Fri, Feb 20, 2009 at 9:18 PM, Theodore A. Roth <taroth@gmail.com>
>> wrote:
>>
>>> 2: Was the documentation branch really last updated on May 9, 2008? Is
>>> there a newer branch I have not yet discovered?
>>
>> Yes, this is likely correct.  Documentation is not OE's strong point.
>> But the combination of various docs available cover things pretty
>> well:
>>
>> http://wiki.openembedded.net/index.php/Documentation
>
> I notice you keep copies of the manual on your website. Last week Koen
> suggested we add docs.openembedded.org to DNS. Would it make sense to go
> ahead and add this address and use it for "static" copies of documentation?

I have a script that automatically updates the docs and rsyncs them to
my web site.  I can adjust that as soon as docs.oe.org comes on line.
Given the reliability of OE infrastructure in the past, it was just a
lot easier to use my own server, but it seems like things are
stabilizing now.

Thanks,
Cliff

-- 
=======================
Cliff Brake
http://bec-systems.com

Re: Documentation/User Manual questions

[Philip Balister]

[-- Attachment #1: Type: text/plain, Size: 1407 bytes --]

Cliff Brake wrote:
> On Wed, Feb 25, 2009 at 9:48 AM, Philip Balister <philip@balister.org> wrote:
>> Cliff Brake wrote:
>>> On Fri, Feb 20, 2009 at 9:18 PM, Theodore A. Roth <taroth@gmail.com>
>>> wrote:
>>>
>>>> 2: Was the documentation branch really last updated on May 9, 2008? Is
>>>> there a newer branch I have not yet discovered?
>>> Yes, this is likely correct.  Documentation is not OE's strong point.
>>> But the combination of various docs available cover things pretty
>>> well:
>>>
>>> http://wiki.openembedded.net/index.php/Documentation
>> I notice you keep copies of the manual on your website. Last week Koen
>> suggested we add docs.openembedded.org to DNS. Would it make sense to go
>> ahead and add this address and use it for "static" copies of documentation?
> 
> I have a script that automatically updates the docs and rsyncs them to
> my web site.  I can adjust that as soon as docs.oe.org comes on line.
> Given the reliability of OE infrastructure in the past, it was just a
> lot easier to use my own server, but it seems like things are
> stabilizing now.

docs.openembedded.org is working now. Koen put a copy of the manual up 
there, but I suspect that long term other documents may also belong 
there. I'm not sure who has access to that part of amethyst/ Cliff, Koen 
and others, can you work out the details of keeping this up to date?

Philip

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/x-pkcs7-signature, Size: 3303 bytes --]

Re: Documentation/User Manual questions

[Sledz, Steffen]

> docs.openembedded.org is working now. Koen put a copy of the 
> manual up 
> there, but I suspect that long term other documents may also belong 
> there. I'm not sure who has access to that part of amethyst/ 
> Cliff, Koen 
> and others, can you work out the details of keeping this up to date?

There's a little configuration problem according to the encoding. The document seems to be in Latin1 and contains

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

but the HTTP header say UTF-8.

HTTP/1.1 200 OK
Date: Mon, 02 Mar 2009 06:45:20 GMT
Server: Apache/2.2.3 (Debian) mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-8+etch13 mod_perl/2.0.2 Perl/v5.8.8
Last-Modified: Tue, 06 May 2008 12:30:38 GMT
ETag: "184311-84-44c8f04003780"
Accept-Ranges: bytes
Content-Length: 132
Connection: close
Content-Type: text/html; charset=UTF-8

This results in wrong presentation e.g. of the copyright symbol. :(

Re: Documentation/User Manual questions

[Cliff Brake]

On Mon, Mar 2, 2009 at 1:48 AM, Sledz, Steffen <sledz@dresearch.de> wrote:
>> docs.openembedded.org is working now. Koen put a copy of the
>> manual up
>> there, but I suspect that long term other documents may also belong
>> there. I'm not sure who has access to that part of amethyst/
>> Cliff, Koen
>> and others, can you work out the details of keeping this up to date?
>
> There's a little configuration problem according to the encoding. The document seems to be in Latin1 and contains
>
> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
>
> but the HTTP header say UTF-8.
>
> HTTP/1.1 200 OK
> Date: Mon, 02 Mar 2009 06:45:20 GMT
> Server: Apache/2.2.3 (Debian) mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-8+etch13 mod_perl/2.0.2 Perl/v5.8.8
> Last-Modified: Tue, 06 May 2008 12:30:38 GMT
> ETag: "184311-84-44c8f04003780"
> Accept-Ranges: bytes
> Content-Length: 132
> Connection: close
> Content-Type: text/html; charset=UTF-8
>
> This results in wrong presentation e.g. of the copyright symbol. :(

I'm unable to reproduce the problem -- can you supply:

- browser and version that displays this problem
- screen shot of problem

Patches are also welcome if you know what needs changed in the docs source.

Thanks,
Cliff

-- 
=======================
Cliff Brake
http://bec-systems.com

Re: Documentation/User Manual questions

[Theodore A. Roth]

[-- Attachment #1: Type: text/plain, Size: 1240 bytes --]

On Tue, Mar 3, 2009 at 8:40 AM, Cliff Brake <cliff.brake@gmail.com> wrote:
> On Mon, Mar 2, 2009 at 1:48 AM, Sledz, Steffen <sledz@dresearch.de> wrote:
>> There's a little configuration problem according to the encoding. The document seems to be in Latin1 and contains
>>
>> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
>>
>> but the HTTP header say UTF-8.
>>
>> HTTP/1.1 200 OK
>> Date: Mon, 02 Mar 2009 06:45:20 GMT
>> Server: Apache/2.2.3 (Debian) mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-8+etch13 mod_perl/2.0.2 Perl/v5.8.8
>> Last-Modified: Tue, 06 May 2008 12:30:38 GMT
>> ETag: "184311-84-44c8f04003780"
>> Accept-Ranges: bytes
>> Content-Length: 132
>> Connection: close
>> Content-Type: text/html; charset=UTF-8
>>
>> This results in wrong presentation e.g. of the copyright symbol. :(
>
> I'm unable to reproduce the problem -- can you supply:
>
> - browser and version that displays this problem
> - screen shot of problem
>
> Patches are also welcome if you know what needs changed in the docs source.
>

I see the same problem on docs.oe.org. I'm using FireFox 3.0.6. When I
build the docs locally, it all looks fine though. I have attached a
screen shot.

Ted Roth

[-- Attachment #2: oe-docs-snap.png --]
[-- Type: image/png, Size: 72221 bytes --]

Re: Documentation/User Manual questions

[Sledz, Steffen]

> > There's a little configuration problem according to the 
> > encoding. The document seems to be in Latin1 and contains
> >
> > <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
> >
> > but the HTTP header say UTF-8.
> >
> > HTTP/1.1 200 OK
> > Date: Mon, 02 Mar 2009 06:45:20 GMT
> > Server: Apache/2.2.3 (Debian) mod_python/3.2.10 Python/2.4.4 PHP/5.2.0-8+etch13 mod_perl/2.0.2 Perl/v5.8.8
> > Last-Modified: Tue, 06 May 2008 12:30:38 GMT
> > ETag: "184311-84-44c8f04003780"
> > Accept-Ranges: bytes
> > Content-Length: 132
> > Connection: close
> > Content-Type: text/html; charset=UTF-8
> >
> > This results in wrong presentation e.g. of the copyright symbol. :(
> 
> I'm unable to reproduce the problem -- can you supply:
> 
> - browser and version that displays this problem
> - screen shot of problem

Theodore sent one some minutes before.

> Patches are also welcome if you know what needs changed in 
> the docs source.

I don't believe it's a problem in the sources but in the apache configuration. It seems that apache does not respect the meta tag inside the document.

Steffen

Re: Documentation/User Manual questions

[Cliff Brake]

2009/2/27 Philip Balister <philip@balister.org>:

> docs.openembedded.org is working now. Koen put a copy of the manual up
> there, but I suspect that long term other documents may also belong there.
> I'm not sure who has access to that part of amethyst/ Cliff, Koen and
> others, can you work out the details of keeping this up to date?

I discussed with Koen -- I'll point a cron job at docs.oe.org, and
keep the html, single page html, and pdf up to date daily.

Thanks,
Cliff

-- 
=======================
Cliff Brake
http://bec-systems.com