Bug 34038

hi,

I beleive this article is very good, and needs to be added to
the FreeBSD Documentation Project.  It certainly helped a lot
of my mates (friends) to solve their a.out problem. :)

Hope it get's in ;)

regards,
Hiten Pandya
<hiten@uk.FreeBSD.org>
<hitmaster@mysun.com>

On Tue, Feb 05, 2002 at 10:20:02AM -0800, Hiten Pandya wrote:
>  I beleive this article is very good, and needs to be added to
>  the FreeBSD Documentation Project.  It certainly helped a lot
>  of my mates (friends) to solve their a.out problem. :)

Hello,

I think that instead of pushing this submission, please provide some
justification *why* this article should go in.

I have just looked over it (which was not exactly made easier by the
submitter who uuencoded *and* tar gzipped the article, which is IMHO
quite gross for a single text file) and I see not a lot of info there
that is not yet in various parts of the Handbook. In some cases, the
info in the article is less accurate than the Handbook, which eg
describes anon FTP and CTM in detail. Also, the text has some incorrect
statements. Eg: mergemaster(8) is not a bash script. There are no bash
scripts in the base system. Also, it says that cvsup needs bandwidth.
While it is true that it will not hurt, in my experience daily cvsup
runs took almost exactly the same amount of time over the 10Mbps link at
university and over a 56kbps modem link. 

Also, I think you should be careful when describing the a.out -> elf
migration path. It was a special case and is probably more trouble than
just running "make upgrade" and "make aout-to-elf". The mailing list
archives from the time when 3.0 was new should be consulted to see any
pitfalls. Also, I think it does not work as easily as described, ie you
cannot simply take the latest STABLE code and upgrade to it from 2.2.x
using source upgrade. Instead, once somebody described the process like
this (after doing it himself)

- First, upgrade to the latest 2.2.8-STABLE.
- Do the upgrade to 3.0 using the a.out -> elf migration path and
  looking at the mailing list archives.
- Upgrade to the latest 3.x-STABLE (which is something like 3.5.1-STABLE
  now)
- Upgrade to 4.0 or 4.1 perhaps.
- Upgrade to the latest 4.x-STABLE.

Yes, it is quite difficult, simply reinstalling from CD or FTP is
probably easier. Merging /etc would be very difficult too. Not to
mention /dev and the fact that you have to recompile many software
packages from third-party source.

The gist: Although cutting corners might work once or twice, the source
upgrade path is actually only for those who are quite good at what they
do and even then you should follow the guidelines.

The text also has stylistic and spelling errors/typos.

Please, before answering, look over the existing documentation set (incl
Handbook, FAQ, etc) and say what information this article has that is
not in one of the existing docs already. If you find any of them lacking
please consider submitting patches there, first.

P.S.: It is easy to loose track of what is already in the docs, because
there so much of it already:-) Eg I just planned to sit down and write a
document about how to connect your FreeBSD box via DSL, but looked in
the Handbook first and found it is already there:-)

P.P.S: This is not to discourage anyone from writing more howto-like docs
for users who prefer that. But duplication within the FDP should be
avoided. Such howtos should be then made available somewhere else.

Hope this message will not be considered flame because it was not the
intention.

-- 
Regards:

Szilveszter ADAM
Szombathely Hungary

I am going to defend the hours of work I did on this document...

Szilveszter Adam wrote:

  
>  Hello,
>  
>  I think that instead of pushing this submission, please provide some
>  justification *why* this article should go in.


Okie, may I do this though?  I hope as the author my reasons will be as 
worthwhile has his!


>  
>  I have just looked over it (which was not exactly made easier by the
>  submitter who uuencoded *and* tar gzipped the article, which is IMHO
>  quite gross for a single text file) and I see not a lot of info there
>  that is not yet in various parts of the Handbook.


http://www.FreeBSD.org/docproj

and I wish to point out Nik Clayton's document suggestion method: tar, 
gzip, uuencode.  For more information about submitting documentation for 
the Docproj, please see the docproj webpage about submitting 
documentation located at:
http://www.freebsd.org/docproj/submitting.html
I know thats kinda cut short, but in essance sums up the uuencode and 
the gzip.  Many people have submitted uuencoded zipped files and have 
had ABSOLUTLY no problems.

> In some cases, the
>  info in the article is less accurate than the Handbook, which eg
>  describes anon FTP and CTM in detail. Also, the text has some incorrect
>  statements. Eg: mergemaster(8) is not a bash script.


 From the mergemaster(8) man page, under DESCRIPTION, and an exact quote:
"mergemaster is a Bourne shell script which is designed to aid you in 
updating the various configuration and other files associated with FreeBSD."

If in some point and time, bash and Bourne again somehow demerged, I 
think that many universities, companies, oganizations, and other 
entities are very miss informed...

> There are no bash
>  scripts in the base system. 


See my above statement... I'm almost positive that mergemaster(8) is in 
the base system.

>  Also, it says that cvsup needs bandwidth.
>  While it is true that it will not hurt, in my experience daily cvsup
>  runs took almost exactly the same amount of time over the 10Mbps link at
>  university and over a 56kbps modem link.


 From the handbook: CTM uses a push method, cvsup uses a pull method, so 
its obvious that CTM is more friendly on the server bandwidth...

If this statement is incorrect, instead of saying my document is wrong, 
tell us the handbook is wrong also so that we can fix it, don't just 
point a finger at one entity please

 
>  
>  Also, I think you should be careful when describing the a.out -> elf
>  migration path. It was a special case and is probably more trouble than
>  just running "make upgrade" and "make aout-to-elf". The mailing list
>  archives from the time when 3.0 was new should be consulted to see any
>  pitfalls. Also, I think it does not work as easily as described, ie you
>  cannot simply take the latest STABLE code and upgrade to it from 2.2.x
>  using source upgrade. Instead, once somebody described the process like
>  this (after doing it himself)


I actually tested this on a 2.2.5 cd that came with an older version of 
"The Complete FreeBSD" written by core member Greg Lehey, took some of 
the information from /usr/src/Makefile, and even read over various 
materials associated with my project.  I even went as far, as to read 
over Greg's methods and information... and talked with a few developers 
on the issue.


>  
>  - First, upgrade to the latest 2.2.8-STABLE.
>  - Do the upgrade to 3.0 using the a.out -> elf migration path and
>    looking at the mailing list archives.
>  - Upgrade to the latest 3.x-STABLE (which is something like 3.5.1-STABLE
>    now)
>  - Upgrade to 4.0 or 4.1 perhaps.
>  - Upgrade to the latest 4.x-STABLE.
>  
>  Yes, it is quite difficult, simply reinstalling from CD or FTP is
>  probably easier. Merging /etc would be very difficult too. Not to
>  mention /dev and the fact that you have to recompile many software
>  packages from third-party source.


During the upgrade process of the SOFTWARE, a few ports still used the 
a.out method, this was during a time that the a.out > ELF transision was 
in progress.  Now that FreeBSD is ELF, and the ports have been cleaned 
up, I see no reason for all this trouble when *I* had none


>  
>  The gist: Although cutting corners might work once or twice, the source
>  upgrade path is actually only for those who are quite good at what they
>  do and even then you should follow the guidelines.
>  
>  The text also has stylistic and spelling errors/typos.


Maybe aspell didn't do its job as well as I thought it would, I have 
been meaning to add information on libraries and other things, maybe 
i'll take another look at it, if your correct on that notion, then its 
an admitted mistake...


>  
>  Please, before answering, look over the existing documentation set (incl
>  Handbook, FAQ, etc) and say what information this article has that is
>  not in one of the existing docs already. If you find any of them lacking
>  please consider submitting patches there, first.


Umm, the Handbook is where I obtained most of my refs, and I will agree 
that the handbook lacks upgrading information, but it is one of the 
things on my to do list.  Unfortunatly, like many, I also lack many free 
hours that could be put to better use.


>  


In either case, thanks for at least taking a look over the document in 
the first place, at least I know someone read over it ;)  For more refs 
of where I got my information I suggest "The Complete FreeBSD" by Greg 
Lehey.  The various written information in the source, the FreeBSD 
Handbook, and the various system man pages.  Thanks alot!!



-- 
Tom (Darklogik) Rhodes
www.Pittgoth.com Gothic Liberation Front
www.FreeBSD.org  The Power To Serve

Hello,

On Tue, Feb 05, 2002 at 05:10:37PM -0500, Tom Rhodes wrote:
> I am going to defend the hours of work I did on this document...

Understandable:-)

> Okie, may I do this though?  I hope as the author my reasons will be as 
> worthwhile has his!

Sure! I read your mail with great interest!

> http://www.FreeBSD.org/docproj
> 
> and I wish to point out Nik Clayton's document suggestion method: tar, 
> gzip, uuencode.  For more information about submitting documentation for 
> the Docproj, please see the docproj webpage about submitting 
> documentation located at:
> http://www.freebsd.org/docproj/submitting.html
> I know thats kinda cut short, but in essance sums up the uuencode and 
> the gzip.  Many people have submitted uuencoded zipped files and have 
> had ABSOLUTLY no problems.

OK I take it back then. (Sigh) I still think that tar-ing a single file
is overkill, simply uuencoding it would have even preserved the indent,
but since it is not a patch, even that is not that important. I was just
thinking along the line: Make it easy for me to deal with it without
going over a lot of steps to decode it first. But if it is in the docs,
I shall shut up:-)

> From the mergemaster(8) man page, under DESCRIPTION, and an exact quote:
> "mergemaster is a Bourne shell script which is designed to aid you in 
> updating the various configuration and other files associated with FreeBSD."
> 
> If in some point and time, bash and Bourne again somehow demerged, I 
> think that many universities, companies, oganizations, and other 
> entities are very miss informed...

<...>

> See my above statement... I'm almost positive that mergemaster(8) is in 
> the base system.

Well, this seems like a case of "miss informed" (sic!) statement then. The
Bourne shell is not bash. Bash is the Bourne *Again* Shell. The confusion
is even made bigger by the fact that many Linux distros simply symlink
sh to bash. But our /bin/sh is not bash, I can tell you.

> From the handbook: CTM uses a push method, cvsup uses a pull method, so 
> its obvious that CTM is more friendly on the server bandwidth...

You are correct but I do not talk about the server side. When you
upgrade your system, you are just using the server. I was talking about
the client side, as I assume you were too in the article.

> I actually tested this on a 2.2.5 cd that came with an older version of 
> "The Complete FreeBSD" written by core member Greg Lehey, took some of 
> the information from /usr/src/Makefile, and even read over various 
> materials associated with my project.  I even went as far, as to read 
> over Greg's methods and information... and talked with a few developers 
> on the issue.

Well if you did test this then I apologise. I still think that it is not
the "supported" method though, there were times when you could not
upgrade even from 3.4 to say 4.2 via "make world" without first going
through 3.x->3.5.1-STABLE->4.0->4.2. It was discussed several times on
the mailing lists that if it works otherwise OK but if you have
problems, always try this way before complaining. I think docs should be
"safe" and document only the supported methods.

> Umm, the Handbook is where I obtained most of my refs, and I will agree 
> that the handbook lacks upgrading information, but it is one of the 
> things on my to do list.  Unfortunatly, like many, I also lack many free 
> hours that could be put to better use.

I think we have a misunderstanding here. I think that the Handbook very
much has info on upgrading, although it probably could be improved. But
this article does not add much to what is already in the Handbook. If
you read the various chapters on installation, on obtaining FreeBSD, on
staying up to date with FreeBSD under "The Cutting Edge", and on using make
world in the same chapter, you will see that almost all is there
already, including stuff you did not describe like CTM, only the "make
upgrade" part is missing. Of course it is nice that you have it now in
one article instead of all over the Handbook, but it is still IMHO
duplication. That is why it is IMHO better idea to just patch the
existing Handbook... also, as I said, some people may prefer shorter
tutorials instead of the Handbook but that is a different story.

-- 
Regards:

Szilveszter ADAM
Szombathely Hungary

Szilveszter Adam wrote:

> The following reply was made to PR docs/34038; it has been noted by GNATS.
> 
> From: Szilveszter Adam <sziszi@bsd.hu>
> To: FreeBSD-gnats-submit@FreeBSD.org
> Cc:  
> Subject: Re: docs/34038
> Date: Tue, 5 Feb 2002 23:40:05 +0100
> 
>  Hello,
>  
>  On Tue, Feb 05, 2002 at 05:10:37PM -0500, Tom Rhodes wrote:
>  > I am going to defend the hours of work I did on this document...
>  
>  Understandable:-)
>  
>  > Okie, may I do this though?  I hope as the author my reasons will be as 
>  > worthwhile has his!
>  
>  Sure! I read your mail with great interest!
>  
>  > http://www.FreeBSD.org/docproj
>  > 
>  > and I wish to point out Nik Clayton's document suggestion method: tar, 
>  > gzip, uuencode.  For more information about submitting documentation for 
>  > the Docproj, please see the docproj webpage about submitting 
>  > documentation located at:
>  > http://www.freebsd.org/docproj/submitting.html
>  > I know thats kinda cut short, but in essance sums up the uuencode and 
>  > the gzip.  Many people have submitted uuencoded zipped files and have 
>  > had ABSOLUTLY no problems.
>  
>  OK I take it back then. (Sigh) I still think that tar-ing a single file
>  is overkill, simply uuencoding it would have even preserved the indent,
>  but since it is not a patch, even that is not that important. I was just
>  thinking along the line: Make it easy for me to deal with it without
>  going over a lot of steps to decode it first. But if it is in the docs,
>  I shall shut up:-)


Perhaps would have been easier, but I felt it may have been more 
approprate ;)


>  
>  > From the mergemaster(8) man page, under DESCRIPTION, and an exact quote:
>  > "mergemaster is a Bourne shell script which is designed to aid you in 
>  > updating the various configuration and other files associated with FreeBSD."
>  > 
>  > If in some point and time, bash and Bourne again somehow demerged, I 
>  > think that many universities, companies, oganizations, and other 
>  > entities are very miss informed...
>  
>  <...>
>  
>  > See my above statement... I'm almost positive that mergemaster(8) is in 
>  > the base system.
>  
>  Well, this seems like a case of "miss informed" (sic!) statement then. The
>  Bourne shell is not bash. Bash is the Bourne *Again* Shell. The confusion
>  is even made bigger by the fact that many Linux distros simply symlink
>  sh to bash. But our /bin/sh is not bash, I can tell you.


Then we should s/bash/Bourne/ as it is listed as a "Bourne shell script" 
in the manual page.  So changing it to Bourne is not a hassle, the main 
point I think is that its still a shell script lol, and I didn't want to 
frighten anyone with "oh no, large merging program/process"  :)


>  
>  > From the handbook: CTM uses a push method, cvsup uses a pull method, so 
>  > its obvious that CTM is more friendly on the server bandwidth...
>  
>  You are correct but I do not talk about the server side. When you
>  upgrade your system, you are just using the server. I was talking about
>  the client side, as I assume you were too in the article.


I tried to cover "both" lol


>  
>  > I actually tested this on a 2.2.5 cd that came with an older version of 
>  > "The Complete FreeBSD" written by core member Greg Lehey, took some of 
>  > the information from /usr/src/Makefile, and even read over various 
>  > materials associated with my project.  I even went as far, as to read 
>  > over Greg's methods and information... and talked with a few developers 
>  > on the issue.
>  
>  Well if you did test this then I apologise. I still think that it is not
>  the "supported" method though, there were times when you could not
>  upgrade even from 3.4 to say 4.2 via "make world" without first going
>  through 3.x->3.5.1-STABLE->4.0->4.2. It was discussed several times on
>  the mailing lists that if it works otherwise OK but if you have
>  problems, always try this way before complaining. I think docs should be
>  "safe" and document only the supported methods.


Could go into the "if it fails" method ;)


>  
>  > Umm, the Handbook is where I obtained most of my refs, and I will agree 
>  > that the handbook lacks upgrading information, but it is one of the 
>  > things on my to do list.  Unfortunatly, like many, I also lack many free 
>  > hours that could be put to better use.
>  
>  I think we have a misunderstanding here. I think that the Handbook very
>  much has info on upgrading, although it probably could be improved. But
>  this article does not add much to what is already in the Handbook. If
>  you read the various chapters on installation, on obtaining FreeBSD, on
>  staying up to date with FreeBSD under "The Cutting Edge", and on using make
>  world in the same chapter, you will see that almost all is there
>  already, including stuff you did not describe like CTM, only the "make
>  upgrade" part is missing. Of course it is nice that you have it now in
>  one article instead of all over the Handbook, but it is still IMHO
>  duplication. That is why it is IMHO better idea to just patch the
>  existing Handbook... also, as I said, some people may prefer shorter
>  tutorials instead of the Handbook but that is a different story.


Truely, but scattered about, and in no way a real "step by step" 
walkthrough, and it does not cover what to do in an a.out situation.  It 
is also a listed project on the docproj webpage, my attempt was to clean 
up the current projects.  Also, I never covered CTM as we need the 
entire source, when I FTP to the CTM directory, the readme tells me that 
its no longer supported.  Emailing the developer (Kemp) got me a reply 
very similar.  Large attempts were made NOT to duplicate information, 
even to the point of taking a few things deeper than I figured required. 
  Since I wrote this though, I have submitted chunchs of information 
about cvsup and other upgrade parts to the handbook, which I think has 
maybe helped that along.


Enjoy,


-- 
Tom (Darklogik) Rhodes
www.Pittgoth.com Gothic Liberation Front
www.FreeBSD.org  The Power To Serve

--- Szilveszter Adam <sziszi@bsd.hu> wrote:
>  I think we have a misunderstanding here. I think that the Handbook very
>  much has info on upgrading, although it probably could be improved. But
>  this article does not add much to what is already in the Handbook. If
>  you read the various chapters on installation, on obtaining FreeBSD, on
>  staying up to date with FreeBSD under "The Cutting Edge", and on using
> make
 
> That is why it is IMHO better idea to just patch the existing Handbook...
 
I don't mean to be against what you say Szilveszter, but I think it would
be nice to have this as a different article, and it would also be nice to
patch the relevant sections in the Handbook as well. :)
 
The other thing is , that, It wouldn't be a good example, to reject this
article just because it is a duplication, and also, it would serve as a bad
example for future developers, and -doc writers for FreeBSD; This is how I
see it ;)
 
regards,
 --Hiten
 --<hiten@uk.FreeBSD.org>

__________________________________________________
Do You Yahoo!?
Send FREE Valentine eCards with Yahoo! Greetings!
http://greetings.yahoo.com

Currently, I am re-evaluating my article.  I've added another 2 
sections, reworded a few parts, and fixed some grammer.  I will be 
reviewing the entire printed article where I will fix grammer and try to 
make some points a bit more clear.  Afterwords, I will put the document 
into the hands of a less-knowledgeable FreeBSD user who will point out 
parts that he/she did not understand or is unclear about.

If anyone out there cares, or has reviewed my current work, and would 
like to make a comment please do so now.  One of the larger aspects is 
the ``getting FreeBSD'' areas, where I tried to walk users through the 
use of CVS, CVSup, and other methods.  Some people think this should be 
scrapped as the handbook describes it, others think that it would be a 
hassle to read parts of the handbook and jump between article and 
handbook...

I do not understand how either method would be applicable as a problem, 
maybe this decision should be left to my ``reviewer'' however, there is 
a place and an ear for every comment availible.

Thanks to everyone for their time, as I know its a lacking aspect, and 
we all need more... ;)

-- 
Tom (Darklogik) Rhodes
www.Pittgoth.com Gothic Liberation Front
www.FreeBSD.org  The Power To Serve

Comment 8 Tom Rhodes 2002-03-28 04:14:05 UTC

Responsible Changed
From-To: freebsd-doc->trhodes

Comment 9 Tom Rhodes 2002-07-02 21:11:41 UTC

State Changed
From-To: open->closed

A chat with Nik has closed this PR.  The article is unrequired