REMINDER: Serial Attached SCSI letter ballot closes next Monday

[Elliott, Robert (Server Storage)]

* From the T10 Reflector (t10 at t10.org), posted by:
* "Elliott, Robert (Server Storage)" <Elliott at hp.com>
*
Reminder: Serial Attached SCSI revision 3 is now in T10 letter ballot,
closing next Monday (23 December 2002).  Although T10 votes have to be
placed by then, comments can in practice be delayed until Monday 30
December (I won't read them until then).

The preferred format for SAS letter ballot comments is an Adobe FDF file
(this requires the full version of Adobe Acrobat).  Lacking that, text
files are fine.

When you place your vote, email the .fdf and/or .txt files to
lohmeyer at t10.org and elliott at hp.com.


Viewing comments
================
Windows:Bookmarks and Window:Comments both make the Bookmarks and
Comments tabs visible on the left.  Select the Comments tab, and all the
comments are listed.  They can be sorted by page, date, author, etc.


Creating comments in Acrobat
============================
1. The text markup tools (shortcut key U; Shift-U cycles through them):
  Highlight tool (pen icon)
  Strikeout tool (S with strikeout icon)
  Underline tool (U with underline icon)
associate a comment with specific words. When you use these tools,
Acrobat seeds the comment with the selected text; you can edit it.

Use Highlight when you're suggesting a change. Format the comment as
"change <selected text> to new text".

Use Strikeout when you're suggesting complete removal. Format the
comment as "remove <selected text>".  

If the selected text is huge, you can replace the innards with "..."

If you're trying to select a link (e.g. "(see Table 37)"), select some
text around the link along with the link.  If you manage to comment just
the link text itself, then clicking on it will follow the link rather
than open the comment box.

2. The graphic markup tools (shortcut key N; Shift-N cycles through
them):
  Square tool (square icon)
  Circle tool (circle icon)
associate a comment with specific areas on the page.  Use these to
highlight parts of figures or large sections of text.

3. The Note tool (paper icon)(shortcut key S) creates an arbitrary
comment on a page, not associated with any particular text.

Please delete any blank comments (right click on it and select Delete).


Menu items
==========
Tools:Spelling:Check Form Fields and Comments
Checks the spelling inside the comments.

Tools:Comments:Summarize
Creates a new .pdf file in memory containing all the comment text.
Always use Sort By Page.  If you have perl, you may use File :Save As:
to save this into a .txt file, then run the .txt file through the perl
program below to create a text file with numbered comments.

File :Export:Comments
outputs all your comments to an .fdf file.

File :Save
saves the .pdf file with comments.


Comment content
===============
Do not include page numbers in the comments.
Start each comment with the section number and name (clear abbreviations
OK). For example:
    7.4.1 CRC overview
    <substance of comment here>

If the comment is in a table or figure, start with both the section
number and the caption:
    7.4.2 CRC generation
    Figure 64 - CRC generator bit order
    <substance of comment here>

If a comment applies to multiple sections, you can just place one
comment on the first occurrence and include all the section numbers:
    7.4.1 CRC overview
    7.4.2 CRC generation
    7.4.3 CRC checking
    <substance of comment here>

If a comment is global, place it on any (preferably the first)
occurrence and add "Global":
    7.4.1 CRC overview
    Global
    <substance of comment>

You don't need to label comments as editorial/technical.  However, if
you think a comment will need discussion by the SAS WG, please add a
line with "***" after the location:
    7.4.3 CRC checking
    ***
    <important comment>


Not using FDF format?
=====================
If you don't have Acrobat, your comments are still welcome in .txt
format.  They need additional text to explain where they apply, though.

1. Number your company's comments starting with #1.
2. Identify the PDF page number. Acrobat shows page numbers like this:
    146 (181 of 417)
   Use the number inside the parenthesis in comments.
3. Identify the section number.
4. Identify the figure or table.
5. Identify the paragraph/sentence or row/column to which the comment
applies.

The text file should look like this:

HP #1
PDF Page 180
7.4.1 CRC Overview
Table 67 - CRC polynomials
Third row
<substance of comment>

HP #2
PDF Page 181
7.4.3 CRC checking
Second paragraph
<substance of comment>

...


Not a T10 member?
=================
Comments are welcome from anyone.  Send them to me and I'll include them
in my own comment set.


Perl program
============
If you want to convert .fdf to .txt yourself, you may use one 
of the following perl programs (for Acrobat 5 or Acrobat 4):

#!/usr/bin/perl5
# Parse Acrobat 5 Annotations into T10 letter ballot comments
# by Rob Elliott, HP
# elliott at hp.com

# Usage:
# Create an Annotations from PDF file
# Select all text in it
# Paste into a text file with a text editor (e.g. vim)
# Save the file and run this script on it
# perl parse_ann5.pl < input.txt > output.txt
#
# Comments are numbered, labels are stripped
use Text::Wrap;     # import wrap()

$Text::Wrap::columns = 76;  # wrap output lines
$prefix = "HP";        # prepend to each comment

while (<>) {
    # most lines start with Page
    # sometimes it gets concatenated to the previous line with .Page
    if (/^Page: (\S+)/) {
        $page = $1;

    } elsif (/^Sequence number: (\d+)/) {
         $item = $1;
         $annotation_count++;

    } elsif (/^Type: /) {
         print "\n$prefix #$annotation_count\nPDF Page $page\n";

    } elsif (/^Author: / || /^Date:/) {

    } else {
        print wrap "", "", $_;
    }
}



#!/usr/local/share/misc/bin/perl5
# Parse Acrobat Annotations into T10 letter ballot comments
# for Acrobat 4
# by Rob Elliott, Compaq Computer Corporation
# robert.elliott at compaq.com

# Usage:
# Create an Annotations from Acrobat PDF file
# Select all text
# Paste into a text file with a text editor (e.g. vim)
# Save the file and run this script on it
# parse_ann < input.txt > output.txt
#
# Comments are numbered, labels are stripped
use Text::Wrap;     # import wrap()

$Text::Wrap::columns = 76;  # wrap output lines
$prefix = "HP";        # prepend to each comment

<>;     # consume the Annotations from mmc3r09 line

while (<>) {
    # most lines start with Page
    # sometimes it gets concatenated to the previous line with .Page
    if (/Page (\d+)\s*$/) {
        $page = $1;

    # most lines start with Annotation
    # sometimes it gets concatenated to the previous line with
.Annotation
    } elsif (/Annotation (\d+); Label.*/) {
        $item = $1;
        $annotation_count++;
        print "\n$prefix $annotation_count\nPDF Page $page\n";
    } else {
        print wrap "", "", $_;
    }
}

--
Rob Elliott, elliott at hp.com
Hewlett-Packard Industry Standard Server Storage Advanced Technology
https://ecardfile.com/id/RobElliott


*
* For T10 Reflector information, send a message with
* 'info t10' (no quotes) in the message body to majordomo at t10.org