POD Formatting (was Re: Literal Values)
Jonathan Scott Duff wrote: Or number the sections like this: =section # blah =section ## subblah =section ### subsubblah =section ## subblah2 =section # blah2 And let the author only worry about sectioning and not about numbering at all. I like that decently. Obviously, making authors specify section numbers would be absurd. It still seems like we have a lot of issues in general with things like bullets, etc., not easily knowing when they're only one paragraph vs. more than one paragraph. I'm still not sure what the preferred generic grouping mechanism is for cases like this, where you need to specify where a previous format ends. In any event, this is good enough for now. Let's redirect all discussion on A Better Pod to the Pod-people list, and go with what we have unless and until they tell us otherwise. Sean M. Burke wrote: On the Pod-people list, we have mostly decided that those inference rules are more trouble than they are worth, precisely because they are unpredictable, and typically there's no way to disable them. I am entirely happy with a future for Pod where no formatter (or, god help us, a parser) thinks it its duty to turn an O(N) solution into an CO(N) solution. You are my hero. MikeL
Re: Literal Values
Mailing-List: contact [EMAIL PROTECTED]; run by ezmlm
From: Angel Faus [EMAIL PROTECTED]
Reply-To: [EMAIL PROTECTED]
Organization: vLex.com
Date: Tue, 12 Nov 2002 21:03:30 +0100
X-SMTPD: qpsmtpd/0.12, http://develooper.com/code/qpsmtpd/
I've written a frist version of the 1.1 - Literal Values subsection
(in Michael's schema).
It discusses the different ways of creating literal numbers and
strings in perl6.
There are no tests, and the format may be outdated. I will gladly
resubmit this in a more complete form.
I have directly stolen some paragraphs from perl5 documentation.
Special prize to the one who lists all the original sources!
This is just a tentative draft, so feel free to delete/add at your own
taste.
Does it look ok? Any comments? (including grammar errors, of course)
-angel
---
=subsection Literal Values
=head1 Literal numbers
=head2 Integers
Integers can be represented by its decimal representation,
such as:
s/Integers/An integer/
my $x = 14; # stores the integer 14 in $x
See the Lquotes section for a full explanation
of the interpolation mechanism and a list of special
characters in doble-quoted strings.
s/doble/double/
=head2 String as vector of ordinals
Literals of the form Cv1.2.3.4 are parsed as a string
composed of characters with the specified ordinals. This
is an alternative, more readable way to construct
(possibly unicode) strings instead of interpolating
characters, as in C\x{1}\x{2}\x{3}\x{4}. The leading Cv
may be omitted if there are more than two ordinals, so
C1.2.3 is parsed the same as Cv1.2.3.
This is equivalent to 256:1.2.3.4
Looks good :)
Luke
Re: Literal Values
On Tue, Nov 12, 2002 at 09:03:30PM +0100, Angel Faus wrote: This is just a tentative draft, so feel free to delete/add at your own taste. Does it look ok? Any comments? (including grammar errors, of course) I've tweaked the first bit on literal integers a bit, see what you think. =subsection Literal Values =head1 Literal numbers =head2 Integers There are many ways to specify literal numeric values in perl, but they default to base 10 for input and output. Once the number has been read by perl it becomes just a magnitude. That is it loses all trace of the way it was originally represented and is just a number. This code for instance prints the literal value 14. my $x = 14; # stores the integer 14 in $x print $x; You can represent the literal value in any other base, using the Cradix: syntax. For example: my $i = 2:101110; # binary my $j = 3:1210112; # tertiary my $k = 8:1270; # octal Printing these would give 46, 1310, and 696 respectively. When the base is greater than 10, there is a need to represent digits that are greater than 9. You can do this in two ways: =over =item * Alphabetic characters: Following the standard convention, perl will interpret the A letter as the digit 10, the B letter as digit 11, and so on. my $l = 16:1E3A7; # hexadecimal =item * Separating by dots: You can also write each digit in its decimal representation, and separate digits using the C. character. my $m = 256:255.255.255.0; # 256-base =back For example, the integer 30 can be written in hexadecimal base in two equivalent ways: my $x = 16:1D my $x = 16:1.14 These two representations are incompatible, so writing something like C16:D.13 will generate a compile-time error. Finally, you can create negative integers by prepending the C- character. For example: my $x = 18; my $y = -18; andrew -- Leo: (July 23 - Aug. 22) The only thing that keeps you from realizing your potential is the depressing awareness that it probably wouldn't take much time or effort. msg24007/pgp0.pgp Description: PGP signature
Re: Literal Values
On Tue, Nov 12, 2002 at 09:03:30PM +0100, Angel Faus wrote: Does it look ok? Sure. Any comments? (including grammar errors, of course) Here are mine. --- =subsection Literal Values =head1 Literal numbers =head2 Integers Integers can be represented by its decimal representation, such as: Integers can be expressed by decimal notation, for instance: my $x = 14; # stores the integer 14 in $x I don't know if it would help or hinder, but I think there should be a sentence like: Decimal notation is the same positional notation we all learned in grade school with the ones position at the far right, then immediately to the left of that is the tens position, then hundreds, and so forth For example, the integer 30 can be written in hexadecimal base in two equivalent ways: my $x = 16:1D my $x = 16:1.14 This two representations are incompatible, so writing something like C16:D.13 will generate a compile-time error. Also note that a compile-time error will be generated if you specify a digit that is larger than your radix can support. For instance, my $x = 3:23; # error Is there some more generic term for number-in-some-arbitrary-radix? Digit always means base-10 numbers to me. (I'll coin radit if I have to ;-) What happens with this one: 256:255.255..0 # same as 256:255.255.0.0 ? # or error? Finally, you can create negative integers prepending the C- character. For example: my $x = 18; my $x = -18; my $x = -256:245.234; my $x = -2:101001; I wonder if all of the my $x = parts should just be removed. The reader doesn't need to know about assignment, variables or scope declarators to learn about literals. -Scott -- Jonathan Scott Duff [EMAIL PROTECTED]
Re: Literal Values
On Tue, Nov 12, 2002 at 09:11:24PM +, Andrew Wilson wrote: For example: my $i = 2:101110; # binary my $j = 3:1210112; # tertiary my $k = 8:1270; # octal Printing these would give 46, 1310, and 696 respectively. Hmm. As companion to specifying numeric literals in an arbitrary radix, I'm sure people will want to know how to output numerics in an arbitrary radix. If perl 6 will have such a facility, a reference to it should go here too. -Scott -- Jonathan Scott Duff [EMAIL PROTECTED]
Re: Literal Values
On Tuesday, November 12, 2002, at 12:03 PM, Angel Faus wrote: =subsection Literal Values =head1 Literal numbers =head2 Integers Rather than using =head, each should be a subsection. What should be the syntax for closing a section? =section title ... =end-section =section title ... =section-end =section title ... =/section =begin section title ... =end section ? MikeL
Re: Literal Values
Angel Faus wrote: I've written a frist version of the 1.1 - Literal Values subsection (in Michael's schema). Alright, I have the tests done to match this section of the documentation. Well, everything except 'bit', since the last time I checked (and this could be resolved by now), there was some debate over Boolean types, and I know bit was included in this argument. Also, I'm still not sure how hashes are supposed to interpolate within strings, and I'm also a bit unsure on how () is supposed to work. On another note, I redid my string and interpolation tests to conform with the Test::More-ish style (including TODO-block tests) that P6C currently uses. Let me know if you like that better than what I did in that last message I sent. New tests are available at: http://jryan.perlmonk.org/images/literaltests.tar.gz
RE: Literal Values
Michael Lazzaro:
# What should be the syntax for closing a section?
How about the empty string? Isn't the end of a section defined by EOF
or when the next section starts?
--Brent Dax [EMAIL PROTECTED]
@roles=map {Parrot $_} qw(embedding regexen Configure)
Wire telegraph is a kind of a very, very long cat. You pull his tail in
New York and his head is meowing in Los Angeles. And radio operates
exactly the same way. The only difference is that there is no cat.
--Albert Einstein (explaining radio)
Re: Literal Values
On Tuesday, November 12, 2002, at 04:08 PM, Brent Dax wrote: Michael Lazzaro: # What should be the syntax for closing a section? How about the empty string? Isn't the end of a section defined by EOF or when the next section starts? I mean if you can have sections inside sections, how do you tell the difference between a child =section and a sibling =section? =section blah =section subblah =section subsubblah =section subblah2 =section blah2 Or do you build the tree in flattened form, and rely on the author to get the numbering right? =section 1 blah =section 1.1 subblah =section 1.1.1 subsubblah =section 1.2 subblah2 =section 2 blah2 MikeL
Re: Literal Values
On Tue, 12 Nov 2002 17:56:28 +, Joseph F. Ryan wrote:
Alright, I have the tests done to match this section of the documentation.
Well, everything except 'bit', since the last time I checked (and this
could be resolved by now), there was some debate over Boolean types, and
I know bit was included in this argument. Also, I'm still not sure how
hashes are supposed to interpolate within strings, and I'm also a bit
unsure on how () is supposed to work.
On another note, I redid my string and interpolation tests to conform with
the Test::More-ish style (including TODO-block tests) that P6C currently
uses. Let me know if you like that better than what I did in that last
message I sent.
For the most part, they look fine to me. I'm a little concerned about some of
the numeric tests:
output_is('CODE', 'OUT', Simple Floats);
print 4.5;
print 0.0;
print 13.12343
CODE
4.50.013.12343
OUT
I'd be more comfortable with a newline between the numbers, just in case. It's
not an issue in the string tests.
-- c
Re: Literal Values
chromatic wrote:
On Tue, 12 Nov 2002 17:56:28 +, Joseph F. Ryan wrote:
For the most part, they look fine to me. I'm a little concerned about some of
the numeric tests:
output_is('CODE', 'OUT', Simple Floats);
print 4.5;
print 0.0;
print 13.12343
CODE
4.50.013.12343
OUT
I'd be more comfortable with a newline between the numbers, just in case. It's
not an issue in the string tests.
-- c
Alright, fine by me; I was wondering on that myself. Done Updated.
RE: Literal Values
Michael Lazzaro:
# On Tuesday, November 12, 2002, at 04:08 PM, Brent Dax wrote:
# Michael Lazzaro:
# # What should be the syntax for closing a section?
#
# How about the empty string? Isn't the end of a section
# defined by EOF
# or when the next section starts?
#
# I mean if you can have sections inside sections, how do you tell the
# difference between a child =section and a sibling =section?
#
# Or do you build the tree in flattened form, and rely on the
# author to
# get the numbering right?
Flattened, because it allows you to split the docs across multiple files
to keep them manageable. I'd like to be able to load the POD up onto my
Palm and edit it on the road, but Documents to Go slows down if the file
gets much over 20K.
--Brent Dax [EMAIL PROTECTED]
@roles=map {Parrot $_} qw(embedding regexen Configure)
Wire telegraph is a kind of a very, very long cat. You pull his tail in
New York and his head is meowing in Los Angeles. And radio operates
exactly the same way. The only difference is that there is no cat.
--Albert Einstein (explaining radio)
Re: Literal Values
Mailing-List: contact [EMAIL PROTECTED]; run by ezmlm Date: Tue, 12 Nov 2002 15:22:53 -0600 From: Jonathan Scott Duff [EMAIL PROTECTED] What happens with this one: 256:255.255..0 # same as 256:255.255.0.0 ? # or error? On the contrary, it's equivalent to 65535 .. 0, or the empty list. -Scott --
Re: Literal Values
On Tue, Nov 12, 2002 at 05:38:00PM -0700, Luke Palmer wrote: Mailing-List: contact [EMAIL PROTECTED]; run by ezmlm Date: Tue, 12 Nov 2002 15:22:53 -0600 From: Jonathan Scott Duff [EMAIL PROTECTED] What happens with this one: 256:255.255..0 # same as 256:255.255.0.0 ? # or error? On the contrary, it's equivalent to 65535 .. 0, or the empty list. Doh! I wasn't thinking about the range operators at all. -Scott -- Jonathan Scott Duff [EMAIL PROTECTED]
Re: Literal Values
output_is('CODE', 'OUT', Simple Floats);
print 4.5;
print 0.0;
print 13.12343
CODE
4.50.013.12343
OUT
I'd be more comfortable with a newline between the numbers, just in case.
It's
not an issue in the string tests.
Alright, fine by me; I was wondering on that myself. Done Updated.
When I look at this, I find myself wanting to separate the control from the
data. Here's an alternative:
my input = qw( 4.5 0.0 13.12343 );
my output = qw( 4.5 0.0 13.12343 ); # can't assume that input==output
my $code = join(;, map {print $_} input);
my $expect = join( , output);
output_is($code, $expect, Simple Floats);
This is, perhaps, slightly harder to grok initially. But its easier to
extend the test data; and also to make control-path changes (such as added
the \n to the print statement). It might be better to use a hash for the
test data.
It is possible to make this type of test much easier to read. A mechanism I
have used in the past is to put the test data into a table (I used html).
Then, you have the test data and expected output as a nice table in a
document; and a simple piece of code to extract tests from it (assuming you
use a perl5 module to parse the table).
Dave.
Re: Literal Values
On Tue, Nov 12, 2002 at 01:20:04PM -0700, Luke Palmer wrote:
: =head2 String as vector of ordinals
:
: Literals of the form Cv1.2.3.4 are parsed as a string
: composed of characters with the specified ordinals. This
: is an alternative, more readable way to construct
: (possibly unicode) strings instead of interpolating
: characters, as in C\x{1}\x{2}\x{3}\x{4}. The leading Cv
: may be omitted if there are more than two ordinals, so
: C1.2.3 is parsed the same as Cv1.2.3.
:
: This is equivalent to 256:1.2.3.4
Not quite. v1.2.3.4 is a string of four characters that only happens
to look like the internal representation of 256:1.2.3.4 on a 32-bit
big-endian machine. And it's perfectly possible to have v1234.4321,
which is a two character string, while 256:1234.4321 is an error.
Larry
Re: Literal Values
On Tue, 12 Nov 2002, Michael Lazzaro wrote: What should be the syntax for closing a section? I'm partial to the LaTeX approach, where you specify the level and the computer figures out the rest. It seems like either level or closing-tag is sufficient by itself. Levels put all the information in one place, and seem to take up less space (hence supporting the idea of pod as lightweight markup). /s
