R SIG Debian - Mar 2015 - Suggestions to improve the info page of /bin/linux/debian

Hi Johannes,

I didn't know what would be the best approach to modify the page?how it was 
generated, is there a central place, etc.?which is why I posted on 
r-sig-debian in the first place. Anyway, although I'm more or less familiar 
with markdown and pandoc, it was easier for me to edit directly README.html 
as it was on CRAN. Please find attached a revision with the modifications I 
suggested earlier. Again, I tried to be correct to the best of my 
knowledge, but I may not be entirely accurate.

I simply edited (and formated the file) using Emacs, and manually added the 
TOC and other suggested modifications (notably reorganization). I think 
there is still room for improvement, but this should get things started. I 
cleaned the layout, but left most of the actual code and text unchanged.

I think the whole page would also benefit from a CSS, e.g. for titles 
(instead of caps), but left it without it.

Best,
Mathieu.


Le 02/03/2015 04:09, Johannes Ranke a ?crit :
> Hi Mathieu,
>
> thanks for your input. It reminds me how I got involved in the Debian
> backports, as I thought the Debian README on CRAN needed an update...
>
> At the moment I do not have the time to reorganize the README, so if you
would
> like to go ahead and implement your changes into a README.html, I
wouldn't
> mind. Otherwise I am willing to pick up your suggestions, but it will take
me
> some time to get around to do it.
>
>  From my work on R package vignettes I know that pandoc is able to generate
> single html documents with linked TOC from markdown, which is more flexible
> than the text2html stuff I am using at the moment (as well as Michael
does).
> But maybe you or someone else on this list knows another convenient way? Or
it
> could be written in HTML using div tags and a hand-crafted css...
>
> Kind regards,
>
> Johannes
>
> Am Donnerstag, 26. Februar 2015, 15:49:58 schrieb Mathieu Basille:
>> After Johannes set up the CRAN repository for Jessie, I had quite some
>> trouble figuring out what any user should do to have a running and
>> up-to-date R in Debian (particularly Testing). Part of the problem is,
I
>> think, the overwhelming documentation on the page "DEBIAN PACKAGES
OF R
>> SOFTWARE" which is provided on CRAN at /bin/linux/debian. Some
information
>> is also lacking in places.
>>
>> So here are a few suggestions to try to arrange this page. The main one
is
>> actually a reorganization of the whole page, which should make it
easier
>> from a user perspective. Note that I think all information I added is
>> correct, but it might not be entirely accurate.
>>
>> I think the page in itself would benefit largely from the inclusion of
a
>> table of contents (with links to sections). With the page reorganized,
that
>> would follow this:
>>
>> INSTALLATION
>>      ADMINISTRATION AND MAINTENANCE
>>      PATHWAYS TO R PACKAGES
>> BACKPORTS ON CRAN
>>      SUPPORTED PACKAGES
>>      DEBIAN WHEEZY (STABLE)
>>      DEBIAN JESSIE (TESTING)
>>      DEBIAN SQUEEZE (OLD STABLE)
>>      DEBIAN SID (UNSTABLE)
>>      SECURE APT
>>      SUPPORTED PLATFORMS
>> REPORTING PROBLEMS
>> BACKPORTING FOR DEBIAN
>> ACKNOWLEDGEMENT
>>
>> I added at the bottom of this message a few modifications of some of
these
>> (sub-)sections. The vast majority of the information is already there,
so
>> these are really minor changes, except for the Jessie sub-section.
>>
>> Hope this helps,
>> Mathieu.
>>
>>
>>
=========================================================================>>
>> INSTALLATION
>>
>> With an appropriate entry in /etc/apt/sources.list *(see below
according to
>> the branch of Debian used)*, the newest R release *including
recommended
>> packages* can be installed using a command sequence like
>>
>>
>> SUPPORTED PACKAGES
>>
>> [Remove:]   r-cran-rmatrix
>>
>>
>> DEBIAN JESSIE (TESTING)
>>
>> As of end of January 2015, there is a new repository containing
binaries
>> for Jessie (current testing). This repository hosts all supported
packages
>> presented above, and is updated upon new R releases.
>>
>> To use R supported packages on Debian Jessie, simply add something like
>>
>>      deb http://<favorite-cran-mirror>/bin/linux/debian
jessie-cran3/
>>
>> to the file /etc/apt/sources.list on your computer. You need to
substitute
>> <favorite-cran-mirror> by one of the mirror URLs listed in
>>
>>      http://cran.r-project.org/mirrors.html
>>
>> Alternatively, it is possible to use APT-pining to install only
R-related
>> packages from SID using Debian official repositories (/!\ Warning:
should
>> be reserved to advanced users already familiar with pining their Debian
>> system). Simply add the supported packages (and other r-cran-* of
interest)
>> in /etc/apt/preferences with a priority greater or equal than the
priority
>> of regular testing packages:
>>
>>      Package: r-base r-base-core r-base-dev r-recommended r-cran-boot
>> r-cran-cluster r-cran-class r-cran-codetools r-cran-foreign
>> r-cran-kernsmooth r-cran-lattice r-cran-mass r-cran-matrix r-cran-mgcv
>> r-cran-nlme r-cran-nnet r-cran-rpart r-cran-spatial r-cran-survival
littler
>> r-cran-rodbc python-rpy python-rpy2 rkward r-cran-jags r-cran-coda
>>      Pin: release o=Debian,a=unstable,l=Debian
>>      Pin-Priority: 900
>>
>>
>> DEBIAN SID (UNSTABLE)
>>
>> The latest stable versions of R and R packages are readily available in
>> official Debian SID repositories.
-- 

~$ whoami
Mathieu Basille
http://ase-research.org/basille

~$ locate --details
University of Florida \\
Fort Lauderdale Research and Education Center
(+1) 954-577-6314

~$ fortune
? Le tout est de tout dire, et je manque de mots
Et je manque de temps, et je manque d'audace. ?
  -- Paul ?luard

Le 03/03/2015 10:02, Mathieu Basille a ?crit :
> Hi Johannes,
>
> I didn't know what would be the best approach to modify the page?how it
was
> generated, is there a central place, etc.?which is why I posted on
> r-sig-debian in the first place. Anyway, although I'm more or less
familiar
> with markdown and pandoc, it was easier for me to edit directly README.html
> as it was on CRAN. Please find attached a revision with the modifications I
> suggested earlier. Again, I tried to be correct to the best of my
> knowledge, but I may not be entirely accurate.
>
> I simply edited (and formated the file) using Emacs, and manually added the
> TOC and other suggested modifications (notably reorganization). I think
> there is still room for improvement, but this should get things started. I
> cleaned the layout, but left most of the actual code and text unchanged.
>
> I think the whole page would also benefit from a CSS, e.g. for titles
> (instead of caps), but left it without it.
Ah! I just noticed that there was actually one (I must be really tired)... 
so let me rephrase that last part: I think the CSS would also benefit from 
an update, e.g. for titles (coding caps in the CSS) and the TOC, but I left 
it unchanged!

Mathieu.

>
> Best,
> Mathieu.
>
>
> Le 02/03/2015 04:09, Johannes Ranke a ?crit :
>> Hi Mathieu,
>>
>> thanks for your input. It reminds me how I got involved in the Debian
>> backports, as I thought the Debian README on CRAN needed an update...
>>
>> At the moment I do not have the time to reorganize the README, so if
you
>> would
>> like to go ahead and implement your changes into a README.html, I
wouldn't
>> mind. Otherwise I am willing to pick up your suggestions, but it will
>> take me
>> some time to get around to do it.
>>
>>  From my work on R package vignettes I know that pandoc is able to
generate
>> single html documents with linked TOC from markdown, which is more
flexible
>> than the text2html stuff I am using at the moment (as well as Michael
does).
>> But maybe you or someone else on this list knows another convenient
way?
>> Or it
>> could be written in HTML using div tags and a hand-crafted css...
>>
>> Kind regards,
>>
>> Johannes
>>
>> Am Donnerstag, 26. Februar 2015, 15:49:58 schrieb Mathieu Basille:
>>> After Johannes set up the CRAN repository for Jessie, I had quite
some
>>> trouble figuring out what any user should do to have a running and
>>> up-to-date R in Debian (particularly Testing). Part of the problem
is, I
>>> think, the overwhelming documentation on the page "DEBIAN
PACKAGES OF R
>>> SOFTWARE" which is provided on CRAN at /bin/linux/debian. Some
information
>>> is also lacking in places.
>>>
>>> So here are a few suggestions to try to arrange this page. The main
one is
>>> actually a reorganization of the whole page, which should make it
easier
>>> from a user perspective. Note that I think all information I added
is
>>> correct, but it might not be entirely accurate.
>>>
>>> I think the page in itself would benefit largely from the inclusion
of a
>>> table of contents (with links to sections). With the page
reorganized, that
>>> would follow this:
>>>
>>> INSTALLATION
>>>      ADMINISTRATION AND MAINTENANCE
>>>      PATHWAYS TO R PACKAGES
>>> BACKPORTS ON CRAN
>>>      SUPPORTED PACKAGES
>>>      DEBIAN WHEEZY (STABLE)
>>>      DEBIAN JESSIE (TESTING)
>>>      DEBIAN SQUEEZE (OLD STABLE)
>>>      DEBIAN SID (UNSTABLE)
>>>      SECURE APT
>>>      SUPPORTED PLATFORMS
>>> REPORTING PROBLEMS
>>> BACKPORTING FOR DEBIAN
>>> ACKNOWLEDGEMENT
>>>
>>> I added at the bottom of this message a few modifications of some
of these
>>> (sub-)sections. The vast majority of the information is already
there, so
>>> these are really minor changes, except for the Jessie sub-section.
>>>
>>> Hope this helps,
>>> Mathieu.
>>>
>>>
>>>
=========================================================================>>>
>>> INSTALLATION
>>>
>>> With an appropriate entry in /etc/apt/sources.list *(see below
according to
>>> the branch of Debian used)*, the newest R release *including
recommended
>>> packages* can be installed using a command sequence like
>>>
>>>
>>> SUPPORTED PACKAGES
>>>
>>> [Remove:]   r-cran-rmatrix
>>>
>>>
>>> DEBIAN JESSIE (TESTING)
>>>
>>> As of end of January 2015, there is a new repository containing
binaries
>>> for Jessie (current testing). This repository hosts all supported
packages
>>> presented above, and is updated upon new R releases.
>>>
>>> To use R supported packages on Debian Jessie, simply add something
like
>>>
>>>      deb http://<favorite-cran-mirror>/bin/linux/debian
jessie-cran3/
>>>
>>> to the file /etc/apt/sources.list on your computer. You need to
substitute
>>> <favorite-cran-mirror> by one of the mirror URLs listed in
>>>
>>>      http://cran.r-project.org/mirrors.html
>>>
>>> Alternatively, it is possible to use APT-pining to install only
R-related
>>> packages from SID using Debian official repositories (/!\ Warning:
should
>>> be reserved to advanced users already familiar with pining their
Debian
>>> system). Simply add the supported packages (and other r-cran-* of
interest)
>>> in /etc/apt/preferences with a priority greater or equal than the
priority
>>> of regular testing packages:
>>>
>>>      Package: r-base r-base-core r-base-dev r-recommended
r-cran-boot
>>> r-cran-cluster r-cran-class r-cran-codetools r-cran-foreign
>>> r-cran-kernsmooth r-cran-lattice r-cran-mass r-cran-matrix
r-cran-mgcv
>>> r-cran-nlme r-cran-nnet r-cran-rpart r-cran-spatial r-cran-survival
littler
>>> r-cran-rodbc python-rpy python-rpy2 rkward r-cran-jags r-cran-coda
>>>      Pin: release o=Debian,a=unstable,l=Debian
>>>      Pin-Priority: 900
>>>
>>>
>>> DEBIAN SID (UNSTABLE)
>>>
>>> The latest stable versions of R and R packages are readily
available in
>>> official Debian SID repositories.
>
-- 

~$ whoami
Mathieu Basille
http://ase-research.org/basille

~$ locate --details
University of Florida \\
Fort Lauderdale Research and Education Center
(+1) 954-577-6314

~$ fortune
? Le tout est de tout dire, et je manque de mots
Et je manque de temps, et je manque d'audace. ?
  -- Paul ?luard

Hi Mathieu,

thanks a lot for your help with this! I just did some minor polishing, and the 
result is now on CRAN.

I tried to make the resulting page validate cleanly, but as the README.html is 
only included in the <body> of the index page, I do not think there is a
way
to include the stylesheet with valid html. The rest of the html validates 
without errors.

I am now using a separate README.css - improvements welcome!

Kind regards,

Johannes


Am Dienstag, 3. M?rz 2015, 10:26:51 schrieb Mathieu
Basille:
> Le 03/03/2015 10:02, Mathieu Basille a ?crit :
> > Hi Johannes,
> > 
> > I didn't know what would be the best approach to modify the
page?how it
> > was
> > generated, is there a central place, etc.?which is why I posted on
> > r-sig-debian in the first place. Anyway, although I'm more or less
> > familiar
> > with markdown and pandoc, it was easier for me to edit directly
> > README.html
> > as it was on CRAN. Please find attached a revision with the
modifications
> > I
> > suggested earlier. Again, I tried to be correct to the best of my
> > knowledge, but I may not be entirely accurate.
> > 
> > I simply edited (and formated the file) using Emacs, and manually
added
> > the
> > TOC and other suggested modifications (notably reorganization). I
think
> > there is still room for improvement, but this should get things
started. I
> > cleaned the layout, but left most of the actual code and text
unchanged.
> > 
> > I think the whole page would also benefit from a CSS, e.g. for titles
> > (instead of caps), but left it without it.
> 
> Ah! I just noticed that there was actually one (I must be really tired)...
> so let me rephrase that last part: I think the CSS would also benefit from
> an update, e.g. for titles (coding caps in the CSS) and the TOC, but I left
> it unchanged!
> 
> Mathieu.
> 
> > Best,
> > Mathieu.
> > 
> > Le 02/03/2015 04:09, Johannes Ranke a ?crit :
> >> Hi Mathieu,
> >> 
> >> thanks for your input. It reminds me how I got involved in the
Debian
> >> backports, as I thought the Debian README on CRAN needed an
update...
> >> 
> >> At the moment I do not have the time to reorganize the README, so
if you
> >> would
> >> like to go ahead and implement your changes into a README.html, I
> >> wouldn't
> >> mind. Otherwise I am willing to pick up your suggestions, but it
will
> >> take me
> >> some time to get around to do it.
> >> 
> >>  From my work on R package vignettes I know that pandoc is able to
> >>  generate
> >> 
> >> single html documents with linked TOC from markdown, which is more
> >> flexible
> >> than the text2html stuff I am using at the moment (as well as
Michael
> >> does). But maybe you or someone else on this list knows another
> >> convenient way? Or it
> >> could be written in HTML using div tags and a hand-crafted css...
> >> 
> >> Kind regards,
> >> 
> >> Johannes
> >> 
> >> Am Donnerstag, 26. Februar 2015, 15:49:58 schrieb Mathieu Basille:
> >>> After Johannes set up the CRAN repository for Jessie, I had
quite some
> >>> trouble figuring out what any user should do to have a running
and
> >>> up-to-date R in Debian (particularly Testing). Part of the
problem is, I
> >>> think, the overwhelming documentation on the page "DEBIAN
PACKAGES OF R
> >>> SOFTWARE" which is provided on CRAN at /bin/linux/debian.
Some
> >>> information
> >>> is also lacking in places.
> >>> 
> >>> So here are a few suggestions to try to arrange this page. The
main one
> >>> is
> >>> actually a reorganization of the whole page, which should make
it easier
> >>> from a user perspective. Note that I think all information I
added is
> >>> correct, but it might not be entirely accurate.
> >>> 
> >>> I think the page in itself would benefit largely from the
inclusion of a
> >>> table of contents (with links to sections). With the page
reorganized,
> >>> that
> >>> would follow this:
> >>> 
> >>> INSTALLATION
> >>> 
> >>>      ADMINISTRATION AND MAINTENANCE
> >>>      PATHWAYS TO R PACKAGES
> >>> 
> >>> BACKPORTS ON CRAN
> >>> 
> >>>      SUPPORTED PACKAGES
> >>>      DEBIAN WHEEZY (STABLE)
> >>>      DEBIAN JESSIE (TESTING)
> >>>      DEBIAN SQUEEZE (OLD STABLE)
> >>>      DEBIAN SID (UNSTABLE)
> >>>      SECURE APT
> >>>      SUPPORTED PLATFORMS
> >>> 
> >>> REPORTING PROBLEMS
> >>> BACKPORTING FOR DEBIAN
> >>> ACKNOWLEDGEMENT
> >>> 
> >>> I added at the bottom of this message a few modifications of
some of
> >>> these
> >>> (sub-)sections. The vast majority of the information is
already there,
> >>> so
> >>> these are really minor changes, except for the Jessie
sub-section.
> >>> 
> >>> Hope this helps,
> >>> Mathieu.
> >>> 
> >>> 
> >>>
=======================================================================>
>>> => >>>
> >>> INSTALLATION
> >>> 
> >>> With an appropriate entry in /etc/apt/sources.list *(see below
according
> >>> to
> >>> the branch of Debian used)*, the newest R release *including
recommended
> >>> packages* can be installed using a command sequence like
> >>> 
> >>> 
> >>> SUPPORTED PACKAGES
> >>> 
> >>> [Remove:]   r-cran-rmatrix
> >>> 
> >>> 
> >>> DEBIAN JESSIE (TESTING)
> >>> 
> >>> As of end of January 2015, there is a new repository
containing binaries
> >>> for Jessie (current testing). This repository hosts all
supported
> >>> packages
> >>> presented above, and is updated upon new R releases.
> >>> 
> >>> To use R supported packages on Debian Jessie, simply add
something like
> >>> 
> >>>      deb http://<favorite-cran-mirror>/bin/linux/debian
jessie-cran3/
> >>> 
> >>> to the file /etc/apt/sources.list on your computer. You need
to
> >>> substitute
> >>> <favorite-cran-mirror> by one of the mirror URLs listed
in
> >>> 
> >>>      http://cran.r-project.org/mirrors.html
> >>> 
> >>> Alternatively, it is possible to use APT-pining to install
only
> >>> R-related
> >>> packages from SID using Debian official repositories (/!\
Warning:
> >>> should
> >>> be reserved to advanced users already familiar with pining
their Debian
> >>> system). Simply add the supported packages (and other r-cran-*
of
> >>> interest)
> >>> in /etc/apt/preferences with a priority greater or equal than
the
> >>> priority
> >>> 
> >>> of regular testing packages:
> >>>      Package: r-base r-base-core r-base-dev r-recommended
r-cran-boot
> >>> 
> >>> r-cran-cluster r-cran-class r-cran-codetools r-cran-foreign
> >>> r-cran-kernsmooth r-cran-lattice r-cran-mass r-cran-matrix
r-cran-mgcv
> >>> r-cran-nlme r-cran-nnet r-cran-rpart r-cran-spatial
r-cran-survival
> >>> littler
> >>> r-cran-rodbc python-rpy python-rpy2 rkward r-cran-jags
r-cran-coda
> >>> 
> >>>      Pin: release o=Debian,a=unstable,l=Debian
> >>>      Pin-Priority: 900
> >>> 
> >>> DEBIAN SID (UNSTABLE)
> >>> 
> >>> The latest stable versions of R and R packages are readily
available in
> >>> official Debian SID repositories.
-- 
PD Dr. Johannes Ranke
Kronacher Str. 8
79639 Grenzach-Wyhlen