Bank holiday? Did you build a rocket and visit the moon in search of cheese?
Say, since you are "over there", any chance of us Yanks getting a fourth
episode of Wallace & Grommit ?
Alan McCollough
Web Programmer
Allaire Certified ColdFusion Developer
Alaska Native Medical Center
> -----Original Message-----
> From: Paul Johnston [SMTP:[EMAIL PROTECTED]]
> Sent: Tuesday, August 29, 2000 2:35 AM
> To: [EMAIL PROTECTED]
> Cc: [EMAIL PROTECTED]; [EMAIL PROTECTED]
> Subject: RE: FuseDoc specification
>
> Living in the UK means that some of use haven't been at work since Friday
> (bank holiday - silly name but is a day off) and so haven't been a part of
> this discussion.
>
> Introduction
> ------------
>
> I created cfdoc with the syntax it has for a reason, and I think that you
> may have all missed (or just overlooked) the point. The syntax looks like
> this:
>
> =cfdoc
> =endcfdoc
> =head '<heading>'
> =subhead '<subheading>'
> =list
> =endlist
> =item
> =b '<bold text>'
> =br
> =code
> =endcode
>
> It is readable.
>
> It is parsable because you look for "=cfdoc" and "=endcfdoc" NOT "= cfdoc"
> and "= endcfdoc". Please note the spaces which are similar to those
> between
> the @ and the descriptive bit of text:
>
> <!---@ Description: Blah! --->
>
> Problems with this
> ------------------
>
> Where does the Description end? Is it at the end of a line (not a good
> idea
> IMHO). For things like that I used a delimiter of a single quote.
>
> I agree that we should have all code in a single comment block and not in
> lots of comment blocks. I like the idea of PDL to code before we start BUT
> lets face facts, unless we come up with a standard (which is what I think
> we
> are doing), people will not code in that way and so will not use the
> correct
> documentation system.
>
> Good parts of fusedoc
> ---------------------
>
> I like the fusedoc ideas of having symbols for in and out variables etc,
> BUT
> (IMHO) these are not immediately understandable (sorry Hal) and so people
> are easily put off from using fusedoc.
>
> Where do we go from here?
> -------------------------
>
> Lee's plan for building the doc structure is excellent (for those of you
> who
> don't know!!!):
>
> 1. Standard General doc syntax
>
> 2. Standard core of comment types
>
> 3. Standard parsed structure
>
> 4. Parser
>
> 5. Display Module
>
> 6. Integrated browser
>
> 7. World domination.
>
> People seem to be fixed on number 1 with using an updated version of
> fusedoc. Fine, but I think it is still confusing and this could cause it
> not to be taken up by a number of people (ie quite a lot of the CF Coding
> profession).
>
> Parsing the Document Syntax
> ---------------------------
>
> If we are writing a syntax to be parsed, then we need the structure of the
> syntax to be foolproof (and yes I do mean that some CF Coders are fools!).
> It must not have spaces or any arbitrary structure that can be played
> with.
>
> Proposal
> --------
>
> I propose changing Hal's syntax in some way to make it word and not symbol
> based. I have no problem with using the general idea, BUT we do need a
> start
> and end tag of some description. An example could be:
>
> --> userID:
> to
> =in or @in
>
> --> [userID]:
> to
> =in-opt or @in-opt
>
> <-> userID:
> to
> =in-out or @in-out
>
> etc.
>
> Not complete and only a suggestion. Please don't tell me I'm fussing over
> little things. The ability to parse and the simplicity to read these
> documents is vitally important. It is also very important to be able to
> pick up the syntax VERY quickly and easily.
>
> I hope this makes sense.
>
> Paul
>
> PS I am still getting good feedback on cfdoc.
>
> PPS If you got here, well done!
>
>
> --------------------------------------------------------------------------
> ----
> To Unsubscribe visit
> http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/fusebox or
> send a message to [EMAIL PROTECTED] with 'unsubscribe' in
> the body.
------------------------------------------------------------------------------
To Unsubscribe visit
http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/fusebox or send a
message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
