Mailing List Archive

Moving the handbooks to the wiki
Hi all

Just a heads-up for everybody - more information will follow of course.

I have started copying the Gentoo handbooks to the Gentoo Wiki. Through
transclusion and semantic wiki, which is supported on Gentoo Wiki, we are
able to do similar reuse of blocks for the architectures.

Given the low resources we are currently having, I think the move to the
wiki will help us with keeping the instructions up to date.

For now, please do not touch anything in the "Handbook:" namespace of the
wiki as I'm going through the effort of migrating it.

Information on translations and so on will follow.

Wkr,
Sven Vermeulen
Re: Moving the handbooks to the wiki [ In reply to ]
On 12/08/14 05:43, Sven Vermeulen wrote:
> Hi all
>
> Just a heads-up for everybody - more information will follow of course.
>
> I have started copying the Gentoo handbooks to the Gentoo Wiki. Through
> transclusion and semantic wiki, which is supported on Gentoo Wiki, we are
> able to do similar reuse of blocks for the architectures.
>
> Given the low resources we are currently having, I think the move to the
> wiki will help us with keeping the instructions up to date.
>
> For now, please do not touch anything in the "Handbook:" namespace of the
> wiki as I'm going through the effort of migrating it.
>
> Information on translations and so on will follow.
>
> Wkr,
> Sven Vermeulen
>
>


FANTASTIC! Good job!

OK, so, just so you know, the gentoo-embedded-handbook is excellent, but
in need of expansion to support either more sections, or a document
linked that is more focus on those new to embedded gentoo. I'm not
a gentoo-dev, but I'm hoping to include this work on the gentoo-wiki,
support the dev that is over the gentoo-embedded handbook, or move
it off of gentoo wiki. That is a decision that you and the
gentoo-embedded herd need to make.

Here is my recent email:





On 12/06/14 14:24, meino.cramer@gmx.de wrote:
> wireless <wireless@tampabay.rr.com> [14-12-06 20:12]:
>> On 12/06/14 13:38, meino.cramer@gmx.de wrote:
>>> Hi,
>>>
>>> recently I bought a great little Linux board: Arietta G25
>>> (http://www.acmesystems.it/arietta)
>>>
>>> Since I like Gentoo I installed it instead of the provided Debian
>>> system. The system I used to compile the kernel is -- of course -- a
>>> Gentoo -- Linux PC.
>>
>>
>> Fantastic effort there Meino!
>>
>> Ok, so looking here:
>>
>> http://www.gentoo.org/proj/en/base/embedded/
>>
>> I cannot determine who is the one to contact to
>> get this offering of current information, correctly
>> formatted to be included in the "boards" section
>> of the gentoo embedded handbook?
>>
>> Next point, Meino has offered up a great bit of information
>> that surely does not belong in the Gentoo embedded handbook,
>> but is a great resource to encourage others how to go about
>> hacking away at a gentoo embedded project. So I think the
>> original email can be listed somewhere for others newer to
>> embedded gentoo hacking, as an example. Where would this
>> be placed? Linked to the handbook as "references" or "notes" or
>> "appendix 1" or such?
>>
>>
>> Also, if there is a format we want folks to follow should the
>> gentoo embedded project page have a suggested format to follow?
>>
>> Many of those listing in the board section merely contain:
>>
>> 1. Board specifications
>> 2. /proc/cpuinfo
>>
>> Maybe the full possible format (optional for the contributor)
>> could have these additional categories:
>>
>> make.conf
>>
>> bootstrap/init details
>>
>> installed packages
>>
>> cross compiling details
>>
>> Native compiling details
>>
>> Special code/hacks included
>> (such as netconsole.c)
>>
>> Libraries
>> ulibC, musl, bionic, glibc
>>
>> languages
>>
>> Added hardware, such as a relay board to
>> power up and down other electronics as an example.
>>
>> So, being a long time reader of gentoo embedded, I understand that
>> most folks in the gentoo-embedded-project space, are busy and have
>> a very deep and strong background in embedded linux. I also understand
>> that they do not need a robustly maintained gentoo-embedded-handbook.
>> But, if we are to encourage others to learn and develop into strong
>> gentoo-embedded hackers, then we should provide a pathway for their
>> needs. Expanding the scope of the gentoo-embedded-manual or creating
>> an ancillary document, with many more simplified steps, would be
>> an excellent first step to revitalizing gentoo-embedded, imho.
>>
>> Personally, I'd like to see what the 64Bit arm devs have in mind for
>> the Gentoo embedded handbook, or as a minimized full (stage?) offering?
>> I've just been waiting for 64Bit arm boards to come down a bit in
>> price; ymmv.
>>
>> I will defer to the leadership decision of the gentoo-embedded-project
>> team.
>>
>> sincerely,
>> James Horton
>>
>
>
> Hi James,
> *thank you for your kind words!*

We're pals right? If so, lifting each other up
is very, very important.

> If I understand it correctly, there are some things
> missing in my initial posting, which are:

> cat /proc/cpuinfo
> make.conf
> Detailed description of the boards hardware

good start. It may be sufficient. Let's wait on some
wider feedback before you do more than this. OK?


> What do you mean with "bootstrap/init" details?
> I simply compiled atp1bootsrap (acmessytems version)
> and it works...I have the strong feeling off missing
> something very important here...


http://stackoverflow.com/questions/25232850/difference-between-bootloader-and-bootstrap-loader


> I did not hack the kernel ... even the serial debug
> connector of the board was not used.

Ok, we'll worry about this once we get something officially
posted and folks try to use it and have questions.
>
> What is missing to complete my posting?

Those categories I listed are an expanded list. You may
not need to put something in all of those categories
I listed. I am "jamming up" the gentoo embedded project
to think about embedded hackers like us. To make provisions
for such and give them ample opportunity to work with us,
before forming a noobs-embedded-gentoo group that works with
new embedded folks and provides much more of a 'turn-key'
embedded experience within gentoo.

>
> Best regards,
> Meino

None may even respond. At that point, I start a new embedded gentoo
project, for guys just like us. OK?


James
Re: Moving the handbooks to the wiki [ In reply to ]
On Mon, Dec 08, 2014 at 10:43:55AM +0000, Sven Vermeulen wrote:
> Just a heads-up for everybody - more information will follow of course.
>
> I have started copying the Gentoo handbooks to the Gentoo Wiki. Through
> transclusion and semantic wiki, which is supported on Gentoo Wiki, we are
> able to do similar reuse of blocks for the architectures.
>
> Given the low resources we are currently having, I think the move to the
> wiki will help us with keeping the instructions up to date.
>
> For now, please do not touch anything in the "Handbook:" namespace of the
> wiki as I'm going through the effort of migrating it.
>
> Information on translations and so on will follow.

An update on this mini-project.

I've made a page [1] on our project wiki space about the handbook
development on the Wiki. It covers
- how the architecture consolidation is done (the alternative of the
GuideXML "include" elements to tie architecture-specific and
architecture-agnostic information together)
- how the parameters (the //value/key stuff in our main handbook XMLs) are
used on the wiki
- pointers about translating the handbook on the wiki

[1] https://wiki.gentoo.org/wiki/Project:Documentation/HandbookDevelopment

I have also copied the AMD64 handbook [2] (the one I have the most affinity
with) already to the wiki to see how things work out. For now, everything is
still marked with "Work in Progress". I am only going to remove that the
moment that the XML files have been updated to point to the Wiki so that
users are "less confused" about what handbook is now the active one.

[2] https://wiki.gentoo.org/wiki/Handbook:AMD64

Comments are always welcome. During the copy, I do notice that there is some
outdated information in the non-installation part of the handbook (perhaps
also in the installation part, but that I can't tell for sure). I am *not*
planning on fixing this before the wiki handbook goes live, although I do
plan to update the handbook on the wiki afterwards.

Yes, that also means that the bugs that are currently reported against the
handbook will need to wait until the wiki move is done - I rather focus on
one thing at a time. And I think that the move to the wiki will also help us
in the sense that developers can then update the instructions themselves
rather than having to go through bugzilla to reach us/me. Efficiency++

Larger changes will of course be communicated and suggested up front on this
mailinglist.

Wkr,
Sven Vermeulen
Re: Moving the handbooks to the wiki [ In reply to ]
On Mon, Dec 08, 2014 at 10:09:50AM -0500, wireless wrote:
> OK, so, just so you know, the gentoo-embedded-handbook is excellent, but
> in need of expansion to support either more sections, or a document
> linked that is more focus on those new to embedded gentoo.

My current efforts are not reflected on the embedded handbook, which is
managed by the embedded team. But I can imagine that they would not mind
that their handbook is also moved to the wiki later using the experience
currently obtained from the "main" handbook.

I'll share my experiences with them when the main handbook is moved so they
can see what way they want to go forward.

Personally, I think that a large amount of information from the handbooks
(both the one I am currently looking at and the embedded one) might be
better off in separate guides/articles on the wiki, with a nice portal for
the project that directs users to the information.

But that's things for later.

Wkr,
Sven Vermeulen
Re: Moving the handbooks to the wiki [ In reply to ]
On 12/10/14 09:43, Sven Vermeulen wrote:
> On Mon, Dec 08, 2014 at 10:09:50AM -0500, wireless wrote:
>> OK, so, just so you know, the gentoo-embedded-handbook is excellent, but
>> in need of expansion to support either more sections, or a document
>> linked that is more focus on those new to embedded gentoo.
>
> My current efforts are not reflected on the embedded handbook, which is
> managed by the embedded team. But I can imagine that they would not mind
> that their handbook is also moved to the wiki later using the experience
> currently obtained from the "main" handbook.
>
> I'll share my experiences with them when the main handbook is moved so they
> can see what way they want to go forward.
>
> Personally, I think that a large amount of information from the handbooks
> (both the one I am currently looking at and the embedded one) might be
> better off in separate guides/articles on the wiki, with a nice portal for
> the project that directs users to the information.
>
> But that's things for later.
>
> Wkr,
> Sven Vermeulen
>
>

Sven,

I trust your judgement. I greatly appreciate your contributions to
Gentoo. I shall be patient.

peace,
James
Re: Moving the handbooks to the wiki [ In reply to ]
On Wed, Dec 10, 2014 at 02:40:06PM +0000, Sven Vermeulen wrote:
> I've made a page [1] on our project wiki space about the handbook
> development on the Wiki. It covers
> - how the architecture consolidation is done (the alternative of the
> GuideXML "include" elements to tie architecture-specific and
> architecture-agnostic information together)
> - how the parameters (the //value/key stuff in our main handbook XMLs) are
> used on the wiki
> - pointers about translating the handbook on the wiki
>
> [1] https://wiki.gentoo.org/wiki/Project:Documentation/HandbookDevelopment
>
> I have also copied the AMD64 handbook [2] (the one I have the most affinity
> with) already to the wiki to see how things work out. For now, everything is
> still marked with "Work in Progress". I am only going to remove that the
> moment that the XML files have been updated to point to the Wiki so that
> users are "less confused" about what handbook is now the active one.
>
> [2] https://wiki.gentoo.org/wiki/Handbook:AMD64
>
> Comments are always welcome. During the copy, I do notice that there is some
> outdated information in the non-installation part of the handbook (perhaps
> also in the installation part, but that I can't tell for sure). I am *not*
> planning on fixing this before the wiki handbook goes live, although I do
> plan to update the handbook on the wiki afterwards.

Hi all

The move, content-wise, is finished. The entry point for all handbooks
(where each individual architecture handbook is linked at) is at
https://wiki.gentoo.org/wiki/Handbook:Main_Page

All architectural handbooks have been moved to the Gentoo Wiki (except for
ARM as it was already marked as not up-to-date anymore). I did a quick
cross-check that there are no wrong blocks being included in the wrong
architecture, so things should work out fine.

I also updated the book.dtd file so that in a few hours (days if people
start objecting) I can start updating the current handbooks to redirect to
the wiki, as well as update the site links to the handbook to point to the
wiki ones.

I will also mail the gentoo-project mailinglist with information so people
are aware of the coming change.

Wkr,
Sven Vermeulen
Re: Moving the handbooks to the wiki [ In reply to ]
On 12/12/2014 09:53 AM, Sven Vermeulen wrote:
> On Wed, Dec 10, 2014 at 02:40:06PM +0000, Sven Vermeulen wrote:
>> I've made a page [1] on our project wiki space about the handbook
>> development on the Wiki. It covers
>> - how the architecture consolidation is done (the alternative of the
>> GuideXML "include" elements to tie architecture-specific and
>> architecture-agnostic information together)
>> - how the parameters (the //value/key stuff in our main handbook XMLs) are
>> used on the wiki
>> - pointers about translating the handbook on the wiki
>>
>> [1] https://wiki.gentoo.org/wiki/Project:Documentation/HandbookDevelopment
>>
>> I have also copied the AMD64 handbook [2] (the one I have the most affinity
>> with) already to the wiki to see how things work out. For now, everything is
>> still marked with "Work in Progress". I am only going to remove that the
>> moment that the XML files have been updated to point to the Wiki so that
>> users are "less confused" about what handbook is now the active one.
>>
>> [2] https://wiki.gentoo.org/wiki/Handbook:AMD64
>>
>> Comments are always welcome. During the copy, I do notice that there is some
>> outdated information in the non-installation part of the handbook (perhaps
>> also in the installation part, but that I can't tell for sure). I am *not*
>> planning on fixing this before the wiki handbook goes live, although I do
>> plan to update the handbook on the wiki afterwards.
> Hi all
>
> The move, content-wise, is finished. The entry point for all handbooks
> (where each individual architecture handbook is linked at) is at
> https://wiki.gentoo.org/wiki/Handbook:Main_Page
>
> All architectural handbooks have been moved to the Gentoo Wiki (except for
> ARM as it was already marked as not up-to-date anymore). I did a quick
> cross-check that there are no wrong blocks being included in the wrong
> architecture, so things should work out fine.
>
> I also updated the book.dtd file so that in a few hours (days if people
> start objecting) I can start updating the current handbooks to redirect to
> the wiki, as well as update the site links to the handbook to point to the
> wiki ones.
>
> I will also mail the gentoo-project mailinglist with information so people
> are aware of the coming change.
>
> Wkr,
> Sven Vermeulen
>
>
Hey Sven, awesome work, it really looks great on the wiki!

One problem that I'm seeing is that it seems that some combination of
characters seem to be getting converted into other characters, like fi,
ff, etc. I don't mind editing them for the PPC handbook, but I was
wondering if that was something you had caught and were fixing already.

Also, when would it be okay to update documentation again? I've got a
bunch of PPC fixes that I hadn't had a chance to update, the wiki
changeover seems like a good opportunity to brush everything up.

Thanks again for your work, this will make our docs better!
-Joe
Re: Moving the handbooks to the wiki [ In reply to ]
On 12/13/2014 12:32 PM, Joseph Jezak wrote:
> On 12/12/2014 09:53 AM, Sven Vermeulen wrote:
>> On Wed, Dec 10, 2014 at 02:40:06PM +0000, Sven Vermeulen wrote:
>>> I've made a page [1] on our project wiki space about the handbook
>>> development on the Wiki. It covers
>>> - how the architecture consolidation is done (the alternative of the
>>> GuideXML "include" elements to tie architecture-specific and
>>> architecture-agnostic information together)
>>> - how the parameters (the //value/key stuff in our main handbook
>>> XMLs) are
>>> used on the wiki
>>> - pointers about translating the handbook on the wiki
>>>
>>> [1]
>>> https://wiki.gentoo.org/wiki/Project:Documentation/HandbookDevelopment
>>>
>>> I have also copied the AMD64 handbook [2] (the one I have the most
>>> affinity
>>> with) already to the wiki to see how things work out. For now,
>>> everything is
>>> still marked with "Work in Progress". I am only going to remove that
>>> the
>>> moment that the XML files have been updated to point to the Wiki so
>>> that
>>> users are "less confused" about what handbook is now the active one.
>>>
>>> [2] https://wiki.gentoo.org/wiki/Handbook:AMD64
>>>
>>> Comments are always welcome. During the copy, I do notice that there
>>> is some
>>> outdated information in the non-installation part of the handbook
>>> (perhaps
>>> also in the installation part, but that I can't tell for sure). I am
>>> *not*
>>> planning on fixing this before the wiki handbook goes live, although
>>> I do
>>> plan to update the handbook on the wiki afterwards.
>> Hi all
>>
>> The move, content-wise, is finished. The entry point for all handbooks
>> (where each individual architecture handbook is linked at) is at
>> https://wiki.gentoo.org/wiki/Handbook:Main_Page
>>
>> All architectural handbooks have been moved to the Gentoo Wiki
>> (except for
>> ARM as it was already marked as not up-to-date anymore). I did a quick
>> cross-check that there are no wrong blocks being included in the wrong
>> architecture, so things should work out fine.
>>
>> I also updated the book.dtd file so that in a few hours (days if people
>> start objecting) I can start updating the current handbooks to
>> redirect to
>> the wiki, as well as update the site links to the handbook to point
>> to the
>> wiki ones.
>>
>> I will also mail the gentoo-project mailinglist with information so
>> people
>> are aware of the coming change.
>>
>> Wkr,
>> Sven Vermeulen
>>
> One problem that I'm seeing is that it seems that some combination of
> characters seem to be getting converted into other characters, like
> fi, ff, etc. I don't mind editing them for the PPC handbook, but I was
> wondering if that was something you had caught and were fixing already.
>
Disregard this, sorry, I had a local issue.

-Joe