Re: [docs] [PATCH 13/34] ref-manual: add pressure limit variable documentation

Michael Opdenacker
2022-10-17T08:16:12Z

Hi Paul,

On 10/16/22 22:38, Paul Eggleton wrote:
> On Tuesday, 11 October 2022 23:30:50 NZDT Michael Opdenacker via
> lists.yoctoproject.org wrote:
>> Actually, these have recently been accepted in the BitBake manual (the
>> patches from Aryaman got accepted after he left WindRiver), though
>> apparently with fewer details:
>> https://git.openembedded.org/bitbake/commit/?id=c014281f72f4f54ec8e681ef2b8e
>> 1080de9ab5cf
>>
>> Shall we submit your updates to the Bitbake manual instead? This way, we
>> don't have these variables documented in two different places.
> Ah, oops - I missed that. I'm OK with that for now; however, and I may have
> also missed if this has been discussed recently, but it's my opinion that all
> variables documented in the BitBake manual should also be in the Yocto
> reference manual, since they are two different contexts - the catch being that
> for some variables there is information you can't reasonably include in the
> bitbake manual since it relies on some definitions unique to OE so the entries
> can't always be copied exactly. If on the other hand some variables only
> appear in the BitBake manual, there will be people who just won't find them.

I agree that BitBake variables should all appear in the Yocto variable
index.

There are already some variables which are initially documented in the
BitBake manual and then the description is expanded in the Yocto manual
according to the OE additions. SRC_URI is one of them:

* https://docs.yoctoproject.org/bitbake/2.0/bitbake-user-manual/bitbake-user-manual-ref-variables.html#term-SRC_URI
* https://docs.yoctoproject.org/ref-manual/variables.html#term-SRC_URI

>
> To avoid things getting out of sync, we could potentially have a script that
> would check for and report on variables present in the BitBake manual that
> aren't in the Yocto reference manual. I'd be happy to write such a script.

This would be useful, but if I recall correctly, Quentin was rather
thinking about having Sphinx include these from the BitBake manual, at
least for the ones which are only defined in the BitBake manual.

Wouldn't it be better than duplicating content, which always causes trouble.

Any further thoughts?

Cheers
Michael.

--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering