[perl #37788] [TODO] dir reorg: move imcc/docs/ to docs/imcc/
Jerry Gay
# Please include the string: [perl #37788]
# in the subject line of all future correspondence about this issue.
# <URL: https://rt.perl.org/rt3/Ticket/Display.html?id=37788 >
this requires makefile changes, and a website generation code update:
(see will at coleda dot com) for assistance.
Note: see the parent ticket for more information.
Jerry Gay via RT
much, as it's a docs dir, but be aware.
~jerry
Jerry Gay via RT
i made some formatting changes and updated links in the documents, and
had to modify the manifest and some html document generation code. all
in all, a pretty simple change.
it would be great if somebody could take a look at the docs as a whole
and rework them where necessary (add index info, make sure links are
valid, format <80 chars per line, etc.) but i believe we already have
tickets for these things.
ticket resolved.
~jerry
Jerry Gay
> 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?
>
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.
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.
~jerry
Larry Wall
: imcc is the compiler for three languages: PIR, PASM, and PAST.
So just rename the directory to P*. Oh, wait...
Larry
Joshua Hoblitt
> > 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
--
Joshua Isom
there's a lot of documentation and I was able to teach myself. That's
not very easy with a lot of other languages. I don't deal at all with
PAST because the best reference documentation would be
examples/past/hello.past and it's not helpful.
I think it'd help to have a wiki available for learning each of pasm,
pir, and past. One of the first things I did to work with pir is port
a couple of the small pasm examples to pir. Because of constant
changes with things within parrot it's hard to keep track of what
you're supposed to do to get what result, and what some new addition
does in an easily understandable way.
Joshua
Joshua Hoblitt
'value' of that time as a tax deduction? If it is, perhaps TPF could
arrange for a 'professional' tech writer to produce some high quality
PIR tutorials/docs as donation.
-J
--
Leopold Toetsch
On Dec 11, 2005, at 0:49, Joshua Isom wrote:
> The documentation thing I've noticed too. A big reason I use perl is
> there's a lot of documentation and I was able to teach myself. That's
> not very easy with a lot of other languages. I don't deal at all with
> PAST because the best reference documentation would be
> examples/past/hello.past and it's not helpful.
PAST isn't much more than 'hello.past'. When you search the p6i
archives you'll find some messages about PAST and that it's up to HLL
authors to specify the nodes and what not.
> I think it'd help to have a wiki available for learning each of pasm,
> pir, and past.
I'd appreciate to have the docs inside parrot, but any effort tp
improve docs is of course welcome.
> Joshua
leo
Bernhard Schmalhofer
>
> PAST isn't much more than 'hello.past'. When you search the p6i
> archives you'll find some messages about PAST and that it's up to HLL
> authors to specify the nodes and what not.
>
In order to increase confusion, 'languages/punie' uses another PAST,
which is kind of derived from Pugs PIL2. See
http://use.perl.org/~Allison/journal/ for details.
Currently I'm retargeting 'Parrot bc' to Allisons PAST.
Seen from a different angle, punie's PAST is a way of exploring what
HLLs need.
CU, Bernhard
CU, Bernhard