Re: How to use programlisting?
| From: | Ron Chmara | Date: | Sat, 06 Jan 2001 20:25:08 +0000 |
| Subject: | Re: How to use programlisting? | ||
| References: | 1 | Groups: | php.doc |
| Request: | Send a blank email to phpdoc+get-969333470@lists.php.net to get a copy of this message | ||
Damien Seguy wrote:
> >> As I'm reading again French translation, I noticed that
> >> programlisting tag seems to have several usage :
> >> <programlisting role="php"> // for PHP script
> >> <programlisting role="php3"> // for PHP3 script
We should probably remove the version-specific ones, en masse,
as the syntax between 3 and 4 didn't change much (at all?)
as far as docbook/jade are concerned, did it?
> >> <programlisting role="apache-conf"> // for apache directive
> >> <programlisting role="apache"> // for apache directive (another
> >> one)
> >> <programlisting role="bs2000"> // for sesam configuration
> >> <programlisting role="makefile"> // for shell commands
> >> <programlisting role="xml"> // for xml code
> >> <programlisting role="html"> // for xml code
> > The most scripts are PHP programs.
> I agree on this, but there are also a pretty good number of alternative :
> some HTML examples (as in features/upload-files.xml)
> some shell commands (as in chapters/install.xml)
> xml and sesam are completely related to their fields, and may not
> have their own "role".
> > Therefore we should use role="php".
> > And the special role="php3.ini" could be renamed to role="php.ini".
> OK for this.
> So, we keep :
> php for PHP,
> php.ini for directive,
> html for HTML
> shell for commands
> all others should not have any role.
> How does this sound like?
Just to question/clarify:
If you showed a perl/tcl/asp script (for php/perl/tcl/asp comparison reasons),
how should it be documented? (I'm wondering what we're doing with "everything
else"). <programlisting> </programlisting> ?
> > Script output could be taged with <computeroutput> and <screen>. It is
> > indeed not a programlisting.
> I think we should use <computeroutput> rather than <screen>.
<computeroutput> 272 occurances
<screen> 129 occurances
Is there a reason for using two different ones?
-Ronabop
--
Personal: ron@opus1.com, 520-326-6109, http://www.opus1.com/ron/
Work: rchmara@pnsinc.com, 520-546-8993, http://www.pnsinc.com/
The opinions expressed in this email are not neccesarrily those of myself,
my employers, or any of the other little voices in my head.