FS#9902 - afterboot manpage feature

Attached to Project: Release Engineering
Opened by Jules (Misfit138) - Saturday, 22 March 2008, 02:54 GMT
Last edited by Dave Reisner (falconindy) - Saturday, 30 July 2011, 20:42 GMT
Task Type Feature Request
Category ArchISO
Status Closed
Assigned To Tobias Powalowski (tpowa)
Simo Leone (neotuli)
Architecture All
Severity Medium
Priority Normal
Reported Version 2007.08-2
Due in Version Undecided
Due Date Undecided
Percent Complete 100%
Votes 8
Private No


Description: After first system boot following an install, an 'afterboot' or perhaps 'firstboot' man page containing either the beginner's guide would be a great advantage, as a checklist and information resource, especially to a system with a non-functional network. This is reminiscent of the OpenBSD 'afterboot' man page. Being a text file, it would be quite small, in line with the slim base system.

Additional info: I am willing to provide an edited version of the beginner's guide in a more readable format if need be. I recommend an edited version of the beginner's guide rather than the official install guide, as I have kept it maintained for the past year or so and will happily continue to maintain it.
It contains quite exhaustive resources to assist in gaining a running system.

This task depends upon

Closed by  Dave Reisner (falconindy)
Saturday, 30 July 2011, 20:42 GMT
Reason for closing:  None
Additional comments about closing:  Old task with no activity. See the wiki.
Comment by Simo Leone (neotuli) - Monday, 14 April 2008, 07:06 GMT
That's a neat idea. I think we might want to just package it and make it like...arch-docs or something. We could put an install guide and beginners guide in there, maybe some other misc stuff. This would be something i'd see fitting in with the installer package (upcoming, it should have been packaged a long time ago).
Comment by Jules (Misfit138) - Monday, 14 April 2008, 18:34 GMT
Great, glad you like the idea. Let me know if I can help.
Comment by Emmanuele Massimi (finferflu) - Tuesday, 15 April 2008, 16:39 GMT
This is a very good idea, I would be very happy to see that happening, it would make Arch even more respectable.
Comment by Greg (dolby) - Monday, 05 May 2008, 23:06 GMT
I am totally against this even though you make it sound good and there is already a volunteer to maintain it. Users should read the Wiki and that is where the Beginners Guide belongs. It might be a good idea if you make some a manpage of the official installation guide but thats about it. Archlinux is not as complicated as OpenBSD and automating tasks that dont need automation is futile.
Comment by Emmanuele Massimi (finferflu) - Tuesday, 06 May 2008, 08:10 GMT
Perhaps you missed the point of the usefulness of such a feature. Not everybody owns two computers, and not everybody gets an internet connection straight at the first boot. How are they going to install without a guide? You might say they could print it, but then having it in a digital form is both more convenient and more ecological.
Comment by Greg (dolby) - Tuesday, 06 May 2008, 12:53 GMT
I think you missed a whole lot more & that is the unusefulness of the feature. The official installation guide is part of the installation iso. If you consider that no guide at all then you are wrong. If you consider that guide inadequate, & want other stuff to be written in it make a feature request or even better submit the text you think its missing. Additionally users can install a web browser right after after or with links being in core even during the installation and read the wiki themselves.
Comment by Greg (dolby) - Tuesday, 06 May 2008, 13:00 GMT
Now that i think of it, may i propose something else instead all the above? As Misfit138 has shown such an interest in documentation and already got involved as a forum admin why dont we make him in changre of maintaining the official installation guide? No need for afterboot, firstboot, unofficial beginners guide or stuff like that.
Comment by Smith Dhumbumroong (zodmaner) - Tuesday, 06 May 2008, 13:13 GMT
I also think this is a very good idea and would like to see it implemented.
Comment by Dan McGee (toofishes) - Tuesday, 06 May 2008, 13:30 GMT
Considering the guy who currently writes the official install guide said "That's a neat idea", the rest of you should probably take your flamewar somewhere more appropriate than this bug report. This isn't the BBS folks. Why the hell would it hurt to have this if someone is willing to maintain it?
Comment by Simo Leone (neotuli) - Saturday, 17 May 2008, 09:50 GMT
Oh damn, I missed the fun part. Anyhow Jules, if you want to get cracking on condensing the beginners guide or maybe scripting a conversion to text (I suggest that option, it'll save you oh so much time). I think this might be something we just want to include on the install CD as part of the installer package right now, which I realize isn't quite what you originally suggested, but it's a start I think.
Comment by Jules (Misfit138) - Monday, 19 May 2008, 03:54 GMT
Ok. I just got back from Dallas, so I'll get started on this in the next couple days.
Comment by Jules (Misfit138) - Monday, 19 May 2008, 17:38 GMT
Ok, here's v1.0, modified, cleaned up and formatted for console. I left the table of contents in for now. Feel free to snip it out if you think it is unnecessary. Enjoy. -Jules
Comment by Jules (Misfit138) - Monday, 19 May 2008, 18:13 GMT
Ok, here's v1.0, modified, cleaned up and formatted for console. I left the table of contents in for now. Feel free to snip it out if you think it is unnecessary. Enjoy. -Jules
Comment by Simo Leone (neotuli) - Friday, 20 June 2008, 08:32 GMT
The copy of the beginners guide you attached has been included in the installer git repo, and will appear on the ISO.
I still think scripting this conversion would be the way to go, so we could really easily update it off the wiki. I tried html2text on the page but the output needed some prettying up. Ideas?
Comment by Jules (Misfit138) - Friday, 20 June 2008, 22:56 GMT
If you like, Simo, here is an updated version with a few minor improvements:

Expanded fstab explanation
Expanded boot scripts explanation
Cut down wordy preamble
Comment by Jules (Misfit138) - Friday, 20 June 2008, 23:00 GMT
It literally takes just a few minutes for me to do this, so if html2text gives us more work than its worth, I can just continue to pin these up here periodically.
If you strongly prefer another method, please advise. :)
Comment by Henning Garus (garns) - Friday, 04 July 2008, 14:56 GMT
I've given autoconversion a try, this is what I came up with. Comments are appreciated :P . It might look a bit weird sometimes, which relates to the heavy usage of '' ''' and ''''' in the wiki Version of the Beginner's Guide.

If there is interest in the script I'll have to clean up the handling of nested lists and some other stuff. Btw usage of ====== (subsubsubsection ?) is plain evil! And caused me to strip one =, which puts About DAEMONS on the same level as the other sections, which does look a bit wrong.
   guide.txt (129.5 KiB)
Comment by Jules (Misfit138) - Friday, 04 July 2008, 15:57 GMT
Looks absolutely terrific! The only thing remaining is to trim out everything pertaining to acquiring and burning the media, since this will already have been done by the time the user is reading it on the installer cd/usb stick. Nice work. I am glad you stepped up to do it, because I am most certainly not qualified, since I cannot script.
Comment by Henning Garus (garns) - Sunday, 06 July 2008, 00:28 GMT
It's done, more or less. Running convertBG.py will download the Beginners Guide from the wiki, strip the part about aquiring Arch and booting the install, use wiki2texi.py to convert the wiki syntax to texinfo and will then run makeinfo to produce the text output.

Depends: texinfo
yes, it would be easy to convert it to do pdf output as well ;)

Things that might break:

wiki2texi is not handling all wiki syntax, espacially it does not handle:

; desc: item
and probably some others I didn't think of.

If these were used, conversion could break or the document could look strange.

The textpart stripping is a bit "unclean" at best, it strips everything between the first line containing "Obtain the latest Installation media" and the first line containing "Start the Installation".
Comment by Greg (dolby) - Wednesday, 23 July 2008, 17:43 GMT
Should this be considered solved or theres still something left to do? AFAIK the beginners guide is part of the latest ISOs
Comment by Jules (Misfit138) - Thursday, 24 July 2008, 02:07 GMT
Sure, seems like there's a script in place for Simo to run for trimming the guide with each release. :)
Comment by Jules (Misfit138) - Thursday, 23 October 2008, 01:57 GMT
Updated guide. 10/22/08
Use it well!
Comment by Glenn Matthys (RedShift) - Thursday, 11 December 2008, 07:36 GMT
Your beginners guide is way too big. Nobody's gonna start reading 155 kilobytes of text. I'm against these kinds of things because the installation guide covers pratically everything to get off the ground. If anything we should advertise the installation guide more.
Comment by Jules (Misfit138) - Wednesday, 17 December 2008, 17:29 GMT
"Your beginners guide is way too big. Nobody's gonna start reading 155 kilobytes of text."

Actually, beginners read it. (Hence the name.)

"I'm against these kinds of things because the installation guide covers pratically everything to get off the ground. If anything we should advertise the installation guide more."

Actually, the installation guide is still included on the installer media as well. It is under /arch/install-guide
The excellent installation guide is adequate for more experienced nix users.

Finally, I would not be against removing the Beginners' Guide, if that is the general consensus among the devs. If that is the case, I can try to tweak the existing install-guide to create a more console-friendly version.

You guys just tell me what you need; I'm willing to do it.
Comment by Vladislav Guberinic (neosisani) - Sunday, 25 January 2009, 00:26 GMT
Maybe make small program (called rtfm for example) that would divide big begginers guide into chapters. One big txt file can look spooky and can be hard to skim trough, especially using less and in small resolutions.

Also some info is out of date, like mentioning of 2007.something installer and lack of ext4 (since that is why most ppl want this release).
Comment by Dieter Plaetinck (Dieter_be) - Monday, 26 January 2009, 19:12 GMT
I agree, not a bad idea. i look at this as a clean/neat way of having the docs available offline.
I don't think this has anything to do with release engineering though, other then that one of the documents would be a beginners guide which happens to be useful after an installation?

Btw imo the package should only contain info/man/txt files, no programs.