Date: Mon, 4 Jun 2001 12:59:05 -0500 From: "G. Adam Stanislav" <adam@whizkidtech.net> To: Murray Stokely <murray@osd.bsdi.com> Cc: freebsd-doc@freebsd.org Subject: Re: Assembly language tutorial Message-ID: <20010604125905.A297@whizkidtech.net> In-Reply-To: <20010604022322.B7096@meow.osd.bsdi.com>; from murray@osd.bsdi.com on Mon, Jun 04, 2001 at 02:23:22AM -0700 References: <3.0.6.32.20010603215127.00a94100@mail85.pair.com> <20010604022322.B7096@meow.osd.bsdi.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Jun 04, 2001 at 02:23:22AM -0700, Murray Stokely wrote: > What is the nature of this source language that you have created? >Why not use SGML as the source language? There is a very powerful >software package that allows you to convert SGML files to many >different formats (jade) and a rich assortment of pre-made stylesheets >for the DocBook DTD (used by the FreeBSD Documentation Project). Unfortunately, every time I try using jade, it crashes. Originally, I was going to write the tutorial in DocBook, but was never able to compile it. I always figured I did not have enough memory for jade (I had 8 Meg), but recently I received an extra 32 Meg from Brett. So, now I have 40 Meg and it still crashes. E.g., right now I went to the directory where I have the cvsupped source for the developers handbook, typed "make" and, sure enough, jade exited on signal 11. >For example, we can easily produce PDF, PostScript, TeX, ASCII, or >HTML versions of your assembly language chapter in the Developer's >Handbook from the SGML source by simply typing "make FORMATS=pdf ..." Hmmm... So, it may not be the darn memory after all! I have just typed "make FORMATS=html" and that worked! > After a quick glance I see a couple of minor errors. The easiest >way to spot them all is to checkout a copy of the developers >handbook and then remove x86/chapter.sgml and replace that file with >your x86.sgml and then try to make the handbook. Yes, now that I got the make to work, I will, :) > If you are really determined to use your own format and >automatically generate SGML, then it would be very helpful if you >could alter your script to follow our indentation style for >readability. Sorry, that is not quite possible at this time. The hed language was designed to remove any indendation (since its main purpose is to create HTML files on the fly, and no indentation means smaller size, hence faster transmission from the server to the browser, with the browser not caring about indentation). What I can do, and started last night, is make it more readable: Right now each paragraph is on a line of its own. I can split the lines to be short, but I cannot indent them easily. I wish I could just run it through tidy, but that expects the file to be in HTML, not SGML. Is there some reformatter available? >> - Second, I need to know how to officially submit future >> additions to the chapter. > > You can send them to this list or me personally and I'll review and >commit it. Very well. I will correct the errors, cut the line length, and let you know when it is ready. I am also editing it so some things are worded differently in the tutorial on my site and in the doc version (e.g., I am talking about "this tutorial" on my site, while "this chapter" in the doc -- and that is where my own language makes it easy :) ). As I continue my work on the tutorial, I will differentiate more between the two versions. For example, my tutorial assumes that you already know what assembly language is, when to use it, and things like that. On the other hand, I should probably explain some of that in the handbook. > Looks good but I'm mostly curious what you're converting from and if >it wouldn't be easier for yourself and everyone else to just maintain >the document in SGML. No, it would not. Not for me, anyway. I use hed (the language of my own design - Html EDitor) extensively on all my web sites. It is a CGI language which can produce different versions of the HTML output based on various environmental variables. That flexibility does not really matter in this tutorial, but it does elsewhere on my sites. Another thing it does: It prevents me from forgetting to close a tag. So, I cannot make a mistake like <b><i>Hello</b>. In hed, I type ^b ^i (Hello). hed then converts it to <b><i>Hello</i></b> automatically. This ability alone was the main reason for me to create hed, and is the main reason why I am not willing to give it up. :) Finally, when I first wrote the tutorial, I had no reason to use DocBook. I mostly wrote the tutorial as a reminder to myself how to do certain things. I never thought it would become as popular as it is (it does get quite a few daily hits), let alone that it might be incorporated into the official FreeBSD documentation. :) I would have done certain things differently if I knew that, and, now that I have seen it inside the handbook, I feel a certain obligation to add some parts that I never considered writing (e.g., I should add some information on the AT&T syntax which is used in assembly language source code of the kernel). That, of course, will take some time, which is the main reason I decided to cut the long lines into short ones, so I can just submit simple diffs for small changes. Eventually, I may even write other chapters for the handbook. I said MAY. :) Cheers, Adam -- Cogitans me cogito esse To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010604125905.A297>