[Rprotobuf-commits] r898 - papers/jss

[noreply at r-forge.r-project.org]

Author: murray
Date: 2014-11-15 03:00:52 +0100 (Sat, 15 Nov 2014)
New Revision: 898

Modified:
   papers/jss/article.Rnw
Log:
Make section 3 a little more concise and address referee feedback by
not having so many small subsections, only using one style and
sticking to it in this section, and not talking about ill defined
'pseudo-methods'.

Sorry I didn't build this yet about to go home wanted to easily
capture some edits on work computer.  hopefully it doesn't break the
build. will be easy to fix if i did.



Modified: papers/jss/article.Rnw
===================================================================
--- papers/jss/article.Rnw	2014-09-25 05:36:52 UTC (rev 897)
+++ papers/jss/article.Rnw	2014-11-15 02:00:52 UTC (rev 898)
@@ -356,8 +356,12 @@
 Message Descriptors are defined in \code{.proto} files and define a
 schema for a particular named class of messages.
 
-\subsection[Importing message descriptors from .proto files]{Importing message descriptors from \code{.proto} files}
+% Note: We comment out subsections in favor of textbf blocks to save
+% space and shrink down this section a little bit.
+%\subsection[Importing message descriptors from .proto files]{Importing message descriptors from \code{.proto} files}
 
+\textbf{Importing message descriptors from \code{.proto} files}
+
 To create or parse a Protocol Buffer Message, one must first read in 
 the message type specification from a \code{.proto} file. 
 A small number of message types are imported when the package is first
@@ -387,11 +391,15 @@
   Fortunately, proper use of namespaces and package imports reduces
   the impact of this for code in packages.}
 
-<<>>=
+% Commented out for now because its too detailed.  Lets shorten
+% section 3 per referee feedback.
+
+<<echo=FALSE,print=FALSE>>=
 ls("RProtoBuf:DescriptorPool")
 @
 
-\subsection{Creating a message}
+% \subsection{Creating a message}
+\textbf{Creating, accessing, and modifying a message.}
 
 New messages are created with the \code{new} function which accepts
 a Message Descriptor and optionally a list of ``name = value'' pairs
@@ -403,11 +411,10 @@
 %function to create messages.
 
 <<>>=
-p1 <- new(tutorial.Person)
 p <- new(tutorial.Person, name = "Murray", id = 1)
 @
 
-\subsection{Access and modify fields of a message}
+%\subsection{Access and modify fields of a message}
 
 Once the message is created, its fields can be queried
 and modified using the dollar operator of \proglang{R}, making Protocol
@@ -434,9 +441,9 @@
 64-bit integer support.  A workaround is available and described in
 Section~\ref{sec:int64} for working with large integer values.
 
+%\subsection{Display messages}
+\textbf{Printing, Reading, and Writing Messages}
 
-\subsection{Display messages}
-
 Protocol Buffer messages and descriptors implement \code{show}
 methods that provide basic information about the message:
 
@@ -452,7 +459,7 @@
 writeLines(as.character(p))
 @
 
-\subsection{Serializing messages}
+% \subsection{Serializing messages}
 
 One of the primary benefits of Protocol Buffers is the efficient
 binary wire-format representation.  
@@ -484,21 +491,24 @@
 readBin(tf2, raw(0), 500)
 @
 
-\code{serialize} can also be called in a more traditional
-object oriented fashion using the dollar operator.
+% TODO(mstokely): commentd out per referee feedback, but see if this is
+% covered in the package documentation well.
+%
+%\code{serialize} can also be called in a more traditional
+%object oriented fashion using the dollar operator.
+%
+%<<>>=
+%p$serialize(tf1)
+%con <- file(tf2, open = "wb")
+%p$serialize(con)
+%close(con)
+%@
+%
+%Here, we first serialize to a file \code{tf1} before we serialize to a binary
+%connection to file \code{tf2}.
 
-<<>>=
-p$serialize(tf1)
-con <- file(tf2, open = "wb")
-p$serialize(con)
-close(con)
-@
+%\subsection{Parsing messages}
 
-Here, we first serialize to a file \code{tf1} before we serialize to a binary
-connection to file \code{tf2}.
-
-\subsection{Parsing messages}
-
 The \pkg{RProtoBuf} package defines the \code{read} and
 \code{readASCII} functions to read messages from files, raw vectors,
 or arbitrary connections.  \code{read} expects to read the message
@@ -533,22 +543,25 @@
 message <- read(tutorial.Person, payload)
 @
 
+% TODO(mstokely): comment out and use only one style, not both per
+% referee feedback.  Also avoid using the term 'pseudo-method' which
+% is unclear.
+%
+%\code{read} can also be used as a pseudo-method of the descriptor
+%object:
+%
+%<<>>=
+%message <- tutorial.Person$read(tf1)
+%con <- file(tf2, open = "rb")
+%message <- tutorial.Person$read(con)
+%close(con)
+%message <- tutorial.Person$read(payload)
+%@
+%
+%Here we read first from a file, then from a binary connection and lastly from
+%a message payload.
 
-\code{read} can also be used as a pseudo-method of the descriptor
-object:
 
-<<>>=
-message <- tutorial.Person$read(tf1)
-con <- file(tf2, open = "rb")
-message <- tutorial.Person$read(con)
-close(con)
-message <- tutorial.Person$read(payload)
-@
-
-Here we read first from a file, then from a binary connection and lastly from
-a message payload.
-
-
 \section{Under the hood: S4 classes, methods, and pseudo methods}
 \label{sec:rprotobuf-classes}