docs: how to spell "bitbake", and docbook semantic markup for user input

docs: how to spell "bitbake", and docbook semantic markup for user input

[Robert P. J. Day]

  just perusing the documentation in my typically pedantic fashion and
a couple questions about style.  first, is the proper spelling
"Bitbake" or "BitBake" since the doc source seems to bounce back and
forth and it really should be consistent.

  and second, this just doesn't seem right as semantic docbook markup:

    "When the <filename>bitbake</filename> command completes ..."

in that context, bitbake is not a filename, it's "userinput".  is
there a reason all user input like that is marked up as "filename"?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Joshua Lock]

On Wed, 2011-07-13 at 06:57 -0400, Robert P. J. Day wrote:
> just perusing the documentation in my typically pedantic fashion and
> a couple questions about style.  first, is the proper spelling
> "Bitbake" or "BitBake" since the doc source seems to bounce back and
> forth and it really should be consistent.

I believe it's the latter, at least that's what I've always use.

Joshua
-- 
Joshua Lock
        Yocto Project "Johannes factotum"
        Intel Open Source Technology Centre

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Darren Hart]

On 07/13/2011 03:48 PM, Joshua Lock wrote:
> On Wed, 2011-07-13 at 06:57 -0400, Robert P. J. Day wrote:
>> just perusing the documentation in my typically pedantic fashion and
>> a couple questions about style.  first, is the proper spelling
>> "Bitbake" or "BitBake" since the doc source seems to bounce back and
>> forth and it really should be consistent.
> 
> I believe it's the latter, at least that's what I've always use.
> 

Agreed:

The man page:
BitBake - simple tool for the execution of tasks

The user manual:
BitBake User Manual

Those seem like the two lines of documentation that are most likely to
be correct :-) So unless Richard or Chris pipe up, I'd go with BitBake.

-- 
Darren Hart
Intel Open Source Technology Center
Yocto Project - Linux Kernel

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Richard Purdie]

On Wed, 2011-07-13 at 20:28 -0700, Darren Hart wrote:
> 
> On 07/13/2011 03:48 PM, Joshua Lock wrote:
> > On Wed, 2011-07-13 at 06:57 -0400, Robert P. J. Day wrote:
> >> just perusing the documentation in my typically pedantic fashion and
> >> a couple questions about style.  first, is the proper spelling
> >> "Bitbake" or "BitBake" since the doc source seems to bounce back and
> >> forth and it really should be consistent.
> > 
> > I believe it's the latter, at least that's what I've always use.
> > 
> 
> Agreed:
> 
> The man page:
> BitBake - simple tool for the execution of tasks
> 
> The user manual:
> BitBake User Manual
> 
> Those seem like the two lines of documentation that are most likely to
> be correct :-) So unless Richard or Chris pipe up, I'd go with BitBake.

I think we've been leaning towards BitBake for a while.

Cheers,

Richard

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Robert P. J. Day]

On Wed, 13 Jul 2011, Darren Hart wrote:

> On 07/13/2011 03:48 PM, Joshua Lock wrote:
> > On Wed, 2011-07-13 at 06:57 -0400, Robert P. J. Day wrote:
> >> just perusing the documentation in my typically pedantic fashion and
> >> a couple questions about style.  first, is the proper spelling
> >> "Bitbake" or "BitBake" since the doc source seems to bounce back and
> >> forth and it really should be consistent.
> >
> > I believe it's the latter, at least that's what I've always use.
> >
>
> Agreed:
>
> The man page:
> BitBake - simple tool for the execution of tasks
>
> The user manual:
> BitBake User Manual
>
> Those seem like the two lines of documentation that are most likely to
> be correct :-) So unless Richard or Chris pipe up, I'd go with BitBake.

  i thought as much, i'm going with that.  not high on any list of
priorities but while i'm perusing the docs, i might as well make notes
of what can change, and submit patches for the more obvious stuff.

  are the small changes i've posted here in acceptable format?  do
they get ACKed at some point so i can verify they were accepted?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Richard Purdie]

On Thu, 2011-07-14 at 05:46 -0400, Robert P. J. Day wrote:
> On Wed, 13 Jul 2011, Darren Hart wrote:
> 
> > On 07/13/2011 03:48 PM, Joshua Lock wrote:
> > > On Wed, 2011-07-13 at 06:57 -0400, Robert P. J. Day wrote:
> > >> just perusing the documentation in my typically pedantic fashion and
> > >> a couple questions about style.  first, is the proper spelling
> > >> "Bitbake" or "BitBake" since the doc source seems to bounce back and
> > >> forth and it really should be consistent.
> > >
> > > I believe it's the latter, at least that's what I've always use.
> > >
> >
> > Agreed:
> >
> > The man page:
> > BitBake - simple tool for the execution of tasks
> >
> > The user manual:
> > BitBake User Manual
> >
> > Those seem like the two lines of documentation that are most likely to
> > be correct :-) So unless Richard or Chris pipe up, I'd go with BitBake.
> 
>   i thought as much, i'm going with that.  not high on any list of
> priorities but while i'm perusing the docs, i might as well make notes
> of what can change, and submit patches for the more obvious stuff.
> 
>   are the small changes i've posted here in acceptable format?  do
> they get ACKed at some point so i can verify they were accepted?

The pieces in poky's documentation directory are part of the yocto-docs
repo which is maintained by Scott (cc'd). Scott is a tech writer rather
than a developer and loves git, er, I mean we might need to help him get
the patches in ;-). Please do send them and we'll figure that bit out
though and will send an acknowledgement when they're merged.

Cheers,

Richard

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Rifenbark, Scott M]

Agreed that BitBake is the correct spelling.  I will be sure to make a sweep through our Yocto manuals and make sure that when we are referring to the tool and not indicating the command they say "BitBake".

Thanks,
ScottR

-----Original Message-----
From: Richard Purdie [mailto:richard.purdie@linuxfoundation.org] 
Sent: Thursday, July 14, 2011 3:02 AM
To: Robert P. J. Day
Cc: Darren Hart; yocto@yoctoproject.org; Rifenbark, Scott M
Subject: Re: [yocto] docs: how to spell "bitbake", and docbook semantic markup for user input

On Thu, 2011-07-14 at 05:46 -0400, Robert P. J. Day wrote:
> On Wed, 13 Jul 2011, Darren Hart wrote:
> 
> > On 07/13/2011 03:48 PM, Joshua Lock wrote:
> > > On Wed, 2011-07-13 at 06:57 -0400, Robert P. J. Day wrote:
> > >> just perusing the documentation in my typically pedantic fashion and
> > >> a couple questions about style.  first, is the proper spelling
> > >> "Bitbake" or "BitBake" since the doc source seems to bounce back and
> > >> forth and it really should be consistent.
> > >
> > > I believe it's the latter, at least that's what I've always use.
> > >
> >
> > Agreed:
> >
> > The man page:
> > BitBake - simple tool for the execution of tasks
> >
> > The user manual:
> > BitBake User Manual
> >
> > Those seem like the two lines of documentation that are most likely to
> > be correct :-) So unless Richard or Chris pipe up, I'd go with BitBake.
> 
>   i thought as much, i'm going with that.  not high on any list of
> priorities but while i'm perusing the docs, i might as well make notes
> of what can change, and submit patches for the more obvious stuff.
> 
>   are the small changes i've posted here in acceptable format?  do
> they get ACKed at some point so i can verify they were accepted?

The pieces in poky's documentation directory are part of the yocto-docs
repo which is maintained by Scott (cc'd). Scott is a tech writer rather
than a developer and loves git, er, I mean we might need to help him get
the patches in ;-). Please do send them and we'll figure that bit out
though and will send an acknowledgement when they're merged.

Cheers,

Richard

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Robert P. J. Day]

On Thu, 14 Jul 2011, Rifenbark, Scott M wrote:

> Agreed that BitBake is the correct spelling.  I will be sure to make
> a sweep through our Yocto manuals and make sure that when we are
> referring to the tool and not indicating the command they say
> "BitBake".

  and while you're at it, i was once lectured sternly that the proper
spelling is "Git" when talking about the tool and "git" when referring
to the actual command.  never "GIT".  at least that what i was told.
do with that what you wish.

rday

p.s.  since i am, at this very moment, immersed in an XML publishing
toolchain, i will probably have some thoughts on docbook markup in the
near future.  stay tuned ...

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Rifenbark, Scott M]

Robert, 

I know that and will work towards that end as well. There are a lot of holdover things in our docs.

Thanks, 
Scott

-----Original Message-----
From: Robert P. J. Day [mailto:rpjday@crashcourse.ca] 
Sent: Thursday, July 14, 2011 7:29 AM
To: Rifenbark, Scott M
Cc: Richard Purdie; Darren Hart; yocto@yoctoproject.org
Subject: RE: [yocto] docs: how to spell "bitbake", and docbook semantic markup for user input

On Thu, 14 Jul 2011, Rifenbark, Scott M wrote:

> Agreed that BitBake is the correct spelling.  I will be sure to make
> a sweep through our Yocto manuals and make sure that when we are
> referring to the tool and not indicating the command they say
> "BitBake".

  and while you're at it, i was once lectured sternly that the proper
spelling is "Git" when talking about the tool and "git" when referring
to the actual command.  never "GIT".  at least that what i was told.
do with that what you wish.

rday

p.s.  since i am, at this very moment, immersed in an XML publishing
toolchain, i will probably have some thoughts on docbook markup in the
near future.  stay tuned ...

Re: docs: how to spell "bitbake", and docbook semantic markup for user input

[Richard Purdie]

On Wed, 2011-07-13 at 06:57 -0400, Robert P. J. Day wrote:
> just perusing the documentation in my typically pedantic fashion and
> a couple questions about style.  first, is the proper spelling
> "Bitbake" or "BitBake" since the doc source seems to bounce back and
> forth and it really should be consistent.
> 
>   and second, this just doesn't seem right as semantic docbook markup:
> 
>     "When the <filename>bitbake</filename> command completes ..."
> 
> in that context, bitbake is not a filename, it's "userinput".  is
> there a reason all user input like that is marked up as "filename"?

I guess it could have been so certain parts appeared in bold but I
suspect there isn't a good reason.

Cheers,

Richard