Mailing List Archive

On Tue, 24 Aug 2004, David Wheeler wrote:

> Hi All,
>
> I'm reading through testing/testing.pod right now, making some changes
> to make its narrative flow a bit better, plus changing the occasional
> grammatical or spelling error (patch to follow). A quick question,
> though: Does the POD processing module that the project use recognize
> the F<> POD tag? This tag identifies files. Right now, the docs are
> using I<> for files, but F<> is more correct. If the POD processing
> that generates the HTML and other formats recognizes F<>, I'd like to
> switch to it.
>
> Thanks,
>
> David

Yes, F<> is understood (I've been using it for the Win32
sections). There's a neat feature in the html conversion -
if there's a (physical) file "foo", F<foo> will become a
link to "foo".

--
best regards,
randy

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

Randy Kobes wrote:
> On Tue, 24 Aug 2004, David Wheeler wrote:
>
>
>>Hi All,
>>
>>I'm reading through testing/testing.pod right now, making some changes
>>to make its narrative flow a bit better, plus changing the occasional
>>grammatical or spelling error (patch to follow). A quick question,
>>though: Does the POD processing module that the project use recognize
>>the F<> POD tag? This tag identifies files. Right now, the docs are
>>using I<> for files, but F<> is more correct. If the POD processing
>>that generates the HTML and other formats recognizes F<>, I'd like to
>>switch to it.
>>
>>Thanks,
>>
>>David
>
>
> Yes, F<> is understood (I've been using it for the Win32
> sections). There's a neat feature in the html conversion -
> if there's a (physical) file "foo", F<foo> will become a
> link to "foo".

Right, and that's why I mostly used F<> where there was a real file to
link to. But feel free to fix those. AFAIK, pod renderers don't make any
difference between F<> and I<>. Or had it changed recently?

--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

On Aug 24, 2004, at 11:53 PM, Stas Bekman wrote:

> Right, and that's why I mostly used F<> where there was a real file to
> link to. But feel free to fix those. AFAIK, pod renderers don't make
> any difference between F<> and I<>. Or had it changed recently?

It's up to the formatter. I tend to prefer semantic markup over styled
markup (F<> being semantic for "This is a file or like a file name" and
I<> meaning "Make this italic") and leave the formatting to the
renderer. For example, HTML output for F<> might be something like <em
class="file">file.name</em>, and then I have the luxury of changing its
appearance via CSS without affecting other em tags.

Regards,

David

David Wheeler wrote:
> On Aug 24, 2004, at 11:53 PM, Stas Bekman wrote:
>
>> Right, and that's why I mostly used F<> where there was a real file to
>> link to. But feel free to fix those. AFAIK, pod renderers don't make
>> any difference between F<> and I<>. Or had it changed recently?
>
>
> It's up to the formatter. I tend to prefer semantic markup over styled
> markup (F<> being semantic for "This is a file or like a file name" and
> I<> meaning "Make this italic") and leave the formatting to the
> renderer. For example, HTML output for F<> might be something like <em
> class="file">file.name</em>, and then I have the luxury of changing its
> appearance via CSS without affecting other em tags.

+1


--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

On Aug 25, 2004, at 9:32 AM, Stas Bekman wrote:

>> It's up to the formatter. I tend to prefer semantic markup over
>> styled markup (F<> being semantic for "This is a file or like a file
>> name" and I<> meaning "Make this italic") and leave the formatting to
>> the renderer. For example, HTML output for F<> might be something
>> like <em class="file">file.name</em>, and then I have the luxury of
>> changing its appearance via CSS without affecting other em tags.
>
> +1

in that case:

--- src/contribute/docs/style.pod.~1.4.~ Tue Jun 18 01:44:11 2002
+++ src/contribute/docs/style.pod Wed Aug 25 16:57:21 2004
@@ -114,8 +114,11 @@

=item *

-Use IE<lt>filenameE<gt> for filenames, URIs and things that are
-generally written in italics.
+Use FE<lt>filenameE<gt> for filenames and URIs.
+
+=item *
+
+Use IE<lt>italicE<gt> for things that are generally written in italics.

=item *

Regards,

David


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

On Aug 25, 2004, at 4:58 PM, David Wheeler wrote:

> in that case:

And also:

--- src/docs/conventions.pod.~1.1.~ Tue Jun 18 01:39:53 2002
+++ src/docs/conventions.pod Wed Aug 25 17:00:59 2004
@@ -40,16 +40,22 @@

=head1 Typographical conventions

-We try to be consisten about our use of different fonts and faces, so
+We try to be consistent about our use of different fonts and faces, so
that you'll recognize special words more easily.

=over

=item *

+F<Filename>
+
+is used for file names, URLs, and such.
+
+=item *
+
I<Italic>

-is used for file names or things you have to replace.
+is used for italicizing

=item *


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

David Wheeler wrote:
> On Aug 25, 2004, at 9:32 AM, Stas Bekman wrote:
>
>>> It's up to the formatter. I tend to prefer semantic markup over
>>> styled markup (F<> being semantic for "This is a file or like a file
>>> name" and I<> meaning "Make this italic") and leave the formatting to
>>> the renderer. For example, HTML output for F<> might be something
>>> like <em class="file">file.name</em>, and then I have the luxury of
>>> changing its appearance via CSS without affecting other em tags.
>>
>>
>> +1
>
>
> in that case:
>
> --- src/contribute/docs/style.pod.~1.4.~ Tue Jun 18 01:44:11 2002
> +++ src/contribute/docs/style.pod Wed Aug 25 16:57:21 2004
> @@ -114,8 +114,11 @@
>
> =item *
>
> -Use IE<lt>filenameE<gt> for filenames, URIs and things that are
> -generally written in italics.
> +Use FE<lt>filenameE<gt> for filenames and URIs.

filenames, directories/paths and URIs?

> +Use IE<lt>italicE<gt> for things that are generally written in italics.

what are the things that are generaly written in italics?

--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

David Wheeler wrote:
> On Aug 25, 2004, at 4:58 PM, David Wheeler wrote:
>
>> in that case:
>
>
> And also:
>
> --- src/docs/conventions.pod.~1.1.~ Tue Jun 18 01:39:53 2002
> +++ src/docs/conventions.pod Wed Aug 25 17:00:59 2004
> @@ -40,16 +40,22 @@
>
> =head1 Typographical conventions
>
> -We try to be consisten about our use of different fonts and faces, so
> +We try to be consistent about our use of different fonts and faces, so
> that you'll recognize special words more easily.
>
> =over
>
> =item *
>
> +F<Filename>
> +
> +is used for file names, URLs, and such.
> +
> +=item *
> +
> I<Italic>

+1

> -is used for file names or things you have to replace.
> +is used for italicizing

Again, italicizing is clear to people familiar with typography (not me), I
guess that's too broad of a concept when we try to give easy to use
guidelines to follow.

--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

On Aug 25, 2004, at 5:02 PM, Stas Bekman wrote:

> filenames, directories/paths and URIs?

Sure, I'll commit that.

>> +Use IE<lt>italicE<gt> for things that are generally written in
>> italics.
>
> what are the things that are generaly written in italics?

Italics are generally used for emphasis, with bold used for even
stronger emphasis (think <em> vs. <strong> in HTML). But note that the
HTML generated by the POD parsers will generally change F<> to <em> or
(blargh) <i>.

Shall I write that?

Regards,

David


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

David Wheeler wrote:
> On Aug 25, 2004, at 5:02 PM, Stas Bekman wrote:
>
>> filenames, directories/paths and URIs?
>
>
> Sure, I'll commit that.
>
>>> +Use IE<lt>italicE<gt> for things that are generally written in italics.
>>
>>
>> what are the things that are generaly written in italics?
>
>
> Italics are generally used for emphasis, with bold used for even
> stronger emphasis (think <em> vs. <strong> in HTML). But note that the
> HTML generated by the POD parsers will generally change F<> to <em> or
> (blargh) <i>.

I guess that's why I never bothered with F<> in first place :) but it's a
bad excuse :)

> Shall I write that?

+1



--
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org

On Aug 25, 2004, at 6:43 PM, Stas Bekman wrote:

>> Shall I write that?
>
> +1

Done.

Regards,

David


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org