On Sat, Dec 10, 2005 at 08:36:46AM -0800, jerry gay wrote: > On 12/10/05, Joshua Hoblitt <[EMAIL PROTECTED]> wrote: > > I really do believe that docs/imcc should be renamed to docs/pir and > > that all references to imcc be removed form docs/pir/*.pod. > > > > Are there any objections to this? > > > imcc is the compiler for three languages: PIR, PASM, and PAST. > therefore, simply renaming docs/imcc/ to docs/pir/ isn't enough. dir > renaming will only make things more clear if there exist appropriate > docs (or stubs for now) for each language. that is, docs describing > pir syntax under docs/pir/, describing past syntax under docs/past/, > and pasm syntax under docs/pasm/. also, a doc describing the imcc > compiler (perhaps directly under docs/.) any related docs, like the > compiler faq should be updated as well.
None of the existing docs/imcc/*.pod files even contain the string PAST (the word 'past' occurs once). PASM syntax is not discussed beyond a) embedding it in PIR and b) generating PASM from PIR. In fact, the only file under docs/imcc that isn't specifically about PIR is operation.pod, which discusses imcc's design. Amusingly, it still describes imcc's *register spilling*. I'm going to go ahead and move everything but docs/imcc/operation.pod into docs/pir unless someone voices an objection. > any steps in this direction would be great. if the first step is > renaming docs/imcc/ to docs/pir/, so be it. but i don't think it ends > there. I believe that you are correct that it does not end there. [below is a general comment, it is in no way directed towards Jerry] I feel that we are in desperate need of clear and easy to understand PIR documentation that is targeted at end users. And that is definitely not the situation at the moment. I read p6i every single day and I have trouble keeping up with the current state of PIR syntax. That just isn't a viable solution for the size of the community this project is hoping to attract. The basic premise we should be following is something like, "If you document it, they will come". Most PIR programmers/Parrot targeters will not care about the name of Parrot's internal subprograms, IMCC is no different. There are a number of competent technical writers on this mailing list that could make a big difference for a fairly modest investment of time. There's no reason that such an effort couldn't become the basis for a 'Learning PIR' book. Any volunteers? Cheers, -J --
pgpHx39f3Nlae.pgp
Description: PGP signature
