Re: Why does the freebsd-doc-en port install far eastern languages?

[Warren Block]

On Thu, 20 Oct 2016, Gary Aitken wrote:


If I build the misc/freebsd-doc-en port, it installs chinese, japanese, and 
korean
fonts.  Can anyone tell me why?

===>>> The following actions will be taken if you choose to proceed:
   Install misc/freebsd-doc-en



   Install chinese/arphicttf
   Install chinese/ttfm
   Install japanese/font-ipa
   Install korean/nanumfonts-ttf


These are a default dependency for the textproc/docproj port.  Turn
off the TRANSLATOR option in that port to avoid them.
___
freebsd-doc@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Building docs

[Warren Block]

On Fri, 6 Jan 2017, scrat wrote:


I am trying to render the documentation from the svn repo for the docs.

I have followed the fdp-primer as well as I can and installed 
textproc/docproj.


Here is what I did

svn checkout https://svn.FreeBSD.org/doc/head ~/doc
cd ~/doc/en_US.ISO8859-1/books/handbook
make FORMATS="html pdf" DESTDIR="~/books/handbook" install


html works

pdf the text is rendered as # ## # etc.

How to fix?


Did you install textproc/docproj as a package or a port?

The "#" symbols indicate a missing font, but that should have been 
installed along with docproj.

___
freebsd-doc@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Building docs

[Warren Block]

On Fri, 6 Jan 2017, scrat wrote:




On 01/06/17 11:22, Warren Block wrote:

On Fri, 6 Jan 2017, scrat wrote:


I am trying to render the documentation from the svn repo for the docs.

I have followed the fdp-primer as well as I can and installed
textproc/docproj.

Here is what I did

svn checkout https://svn.FreeBSD.org/doc/head ~/doc
cd ~/doc/en_US.ISO8859-1/books/handbook
make FORMATS="html pdf" DESTDIR="~/books/handbook" install


html works

pdf the text is rendered as # ## # etc.

How to fix?


Did you install textproc/docproj as a package or a port?


I installed by ports using synth.  Built from 2017Q1 branch port.


Well, okay, but what I'm trying to determine is whether the options were 
the defaults or not.  The correct fonts for PDF generation should be 
installed when the FOP option is set. Installing fop on its own as a 
separate package might not do that.

___
freebsd-doc@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Translation Projects - Language: Català

[Warren Block]

On Sun, 15 Jan 2017, Josep Maria Gasset wrote:


 Dear doc members,

Does anyone know if there are anybody is translating handbook & faqs
to Català language and a main web page of Freebsd.org/cat?

Maybe I can contribute to this project.


That would be excellent!  Please see the FDP Quick Start:

https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/overview.html#overview-quick-start

and the PO Translations chapter:

https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/po-translations.html


The Quick Start also lists the mailing lists and IRC channels for help. 
There is also a FreeBSD-Translators mailing list:

https://lists.freebsd.org/mailman/listinfo/freebsd-translators
___
freebsd-doc@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Introduction & question / comment regarding source tree documentation

[Warren Block]

On Wed, 1 Mar 2017, Peter Looyenga wrote:


My current drive: I can't help feel that the steps required to obtain the
source tree aren't very well explained, and as a result several people and
up confused. To put it more blunt, this thread is what drove me to try and
take more action:

https://forums.freebsd.org/threads/59919/



My only concern (and actual question): Is this already work in progress by
any chance? I don't mind spending a good amount of time on writing up some
documentation, but I have a little bit of a problem with setting something
up only to find out that it wasn't needed at all.


It is needed.  I have some work already on this related part:
https://reviews.freebsd.org/D7665


Note: I don't mind if I send in suggestions and then see them not getting
accepted, that's all part of the game. But it would be bad for me when I
start working on this, only to discover that someone else was already
working on it so I basically ended up wasting my time.

Hope you guys can give me some pointers on this.


Please see the FDP Primer for general guides:
https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html
___
freebsd-doc@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: mistakes in documentation (ошибки в документации)

[Warren Block]

If you know of anyone interested in doing a Russian translation, the PO 
translation system makes it significantly easier than in the past:


https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/po-translations.html

On Wed, 14 Jun 2017, Maxim Konovalov wrote:


Hi Max,

On Wed, 14 Jun 2017, 13:01+0300, Rys, Max wrote:


Куда писать про ошибки в документации?

https://www.freebsd.org/doc/ru_RU.KOI8-R/books/handbook/openssh.html

   - "Поскольку файлы *файлы* передаются по сети..."
   - "каждый раз *для* при использовании"
   - "порту соединения переправляются *на* через SSH на определенный"


I fixed these typos -- thanks for reporting.

In future it makes sense to use FreeBSD Bugzilla to report such
issues:

https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation

Also, I'd recommend to use English documentation instead as the
Russian translation project has no significant activity for long time.



___
freebsd-doc@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Porters Handbook section 4.4

[Warren Block]

On Mon, 25 Sep 2017, Russell Haley wrote:


Thanks! I'll play with this on the weekend.


Please create a review at https://reviews.freebsd.org/ and add me as a 
reviewer.


Thanks!
___
freebsd-doc@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [CFR] Migrating the documentation to a real XML toolchain

[Warren Block]

On Thu, 14 Mar 2013, Gabor Kovesdan wrote:


Em 27-02-2013 02:24, Warren Block escreveu:
Author info is a little off.  Compare the authors at the start of the 
bsdinstall chapter:
http://people.freebsd.org/~gabor/db45/en_US.ISO8859-1/books/handbook/bsdinstall.html 
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/bsdinstall.html


In the standard version, each section is rendered as a sentence, with 
multiple authors separated by commas.


Acronyms don't have any highlights, they just look like normal text.

Thank you Warren for the exhaustive list, I've been fixing the issues you 
reported. However, I don't find highlighted acronyms in the old rendering 
either. Could you please point me to a concrete example, please?


Good question.  I know this is given as a reason why acronyms should 
always be marked up, and I thought I'd seen it at some point in the 
FreeBSD docs.  But it does not do it now, and I may have been looking at 
something else.  It is something that would really benefit the reader.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Need help documenting development processes in FreeBSD

[Warren Block]

On Mon, 1 Apr 2013, Garrett Cooper wrote:


   In order to bring contributors up to speed on how to interact with
FreeBSD, I want to document some of the items that aren't really noted in
the FreeBSD developers or committers handbook. Some topics that come to
mind are "How do I do a precommit build?" (tinderbox, etc), "How do I test
my changes?" (there's a chapter, but it's not helpful), "How do I get
involved with the project?", "How do I build quickly?", "What are mtree
files?", etc.
   I was wondering if a) there are any other developers interested in this
effort, b) where it should go (in the dev handbook?), and c) who would be
interested in reviewing the work? I'd like to put it up on the wiki first
(as I'm not an SGML wizard) and put it in SGML eventually, but I need
feedback on whether or not this is doable.


This is interesting to me.  I'd suggest an outline first, and not 
worrrying about markup until a rough framework is done.  I can help with 
markup and review.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [CFR] Migrating the documentation to a real XML toolchain

[Warren Block]

On Thu, 4 Apr 2013, Gabor Kovesdan wrote:


Em 26-02-2013 22:56, Gabor Kovesdan escreveu:
I have some improvements for the doc infrastructures in the xml-tools 
branch. I think that the changeset is now getting mature enough to be 
merged back so I'd like to ask for review. It does not affect the web 
pages, only books and articles. The rendered docs are available at:

http://people.freebsd.org/~gabor/db45/

For every article/book, you will find there the chunked XHTML docs or if 
you manually enter the URL, you can access the single XHTML and PDF 
versions as (article|book)\.(html|pdf). 


Thank you for all the feedback I got! I've fixed the problems reported and 
the regenerated result is online at the same location.


I'm still encouraging you to review it again and check if you find something 
broken. The new rendering process is quite different from the old one so 
there are differences in the output (e.g. whether the navigation 
header/footer has numbered chapter titles or not). Please report only 
differences that are clearly wrong or those that you think that are worse in 
the new output and do not report just the fact that something differs.


Looking at the HTML Handbook:

The copyright in the original is a link, but is not in the new version. 
Not sure how important that might be.



After the two legal notice links at the start, there is a "February 
1999" text in the new version.



Links to other chapters are better in the new version.  It shows the 
chapter number but also the title.  Nice!



The callouts don't line up the same in these two sections:
New: 
http://people.freebsd.org/~gabor/db45/en_US.ISO8859-1/books/handbook/bsdinstall-start.html#idp67265936

Old:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/bsdinstall-start.html#AEN1480

Could be a whitespace parsing issue, or just a change in the source that 
has not been copied over.



I didn't see any serious problems in a quick look.  There are some minor 
formatting differences, spacing in tables and such, but the new version 
looks okay to me.



PDF Handbook:

Some links show a relative path rather than a URL.  From page 2 of the 
PDF:


  You may also want to search the handbook
  (../../../../search/index.html).


Some bulleted lists are shown with the bullet on a blank line (actual 
page 23, logical page 3).



Indents on author attributions which should probably not be there 
(actual page 30, logical page 10).



Graphic images are not scaled down to fit the page width.  See actual 
page 37, logical page 17 for an example.



Text in some elements (?) is not wrapped, but the old version 
did not do that either (actual page 38, logical page 18).  Using a 
somewhat smaller font for these would help.


That's enough for now, I think.  Thanks again for your work on this!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Type Error FreeBSD handbook

[Warren Block]

On Fri, 5 Apr 2013, ruediger.r...@dlr.de wrote:


Hello!

I discovered a type error by accident:
There is a 'be' (the word, not the letter) missing in the current online 
version of Chapter 4.3.2:
"Several file flags may only added"


Fixed in r41373.  Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [patch] en/handbook/ports: another small cleanup

[Warren Block]

On Thu, 11 Apr 2013, Taras Korenko wrote:


 Hi, folks.

 Could anyone of doc@ review/comment/approve the following small changes
to en/books/handbook/ports ?


 1) An obvious chunk:

Index: en_US.ISO8859-1/books/handbook/ports/chapter.xml
===
--- en_US.ISO8859-1/books/handbook/ports/chapter.xml(revision 41406)
+++ en_US.ISO8859-1/books/handbook/ports/chapter.xml(working copy)
@@ -116,7 +116,7 @@
  commands.

Both packages and ports understand
-  dependencies. If &man.pkg.add.1; or the
+  dependencies.  If &man.pkg.add.1; or the
  Ports Collection is used to install an application and a
  dependent library is not already installed, the library will
  automatically be installed first.
@@ -1337,7 +1337,7 @@

  Once the compile is complete, you are returned to the
prompt.  The next step is to install the port using
-   make install:
+   make install:


Agreed on the command tags, but I'm not sure the maketarget tags are 
needed there.  Can't say they should not be there either, though.



  &prompt.root; make install
===>  Installing for lsof-4.57
@@ -1670,22 +1670,22 @@

  
Root ports: no dependencies and is not depended on
- by other ports
+ by other ports;
  

  
Trunk ports: no dependencies, but other ports depend
- upon it
+ upon it;
  

  
Branch ports: have dependencies and are depended
- upon by other ports
+ upon by other ports;
  

  
Leaf ports: have dependencies but are not depended
- upon by other ports
+ upon by other ports.
  



Adding those semicolons and the period makes those entries into a long 
sentence, or tries.  But they are already in a list, so this seems 
unnecessary.  Besides, semicolons are kind of weakly evil.  Using them 
as a supercomma is not so bad, but still...  Also, they may have to be 
entered as ;.  Or maybe not, I've lost track.






 2) A controversial one:

Index: en_US.ISO8859-1/books/handbook/ports/chapter.xml
===
--- en_US.ISO8859-1/books/handbook/ports/chapter.xml(revision 41406)
+++ en_US.ISO8859-1/books/handbook/ports/chapter.xml(working copy)
@@ -1778,7 +1778,8 @@

  
The portsclean utility is part of the
- portupgrade suite.
+ ports-mgmt/portupgrade
+ suite.
  


Seems okay to me.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Changing the documentation's font style.

[Warren Block]

On Fri, 12 Apr 2013, Isabell Long wrote:


Hi all,

I sent this idea to the #bsddocs IRC channel a few days ago and no-one
there objected, but here you go. I'd like to know your opinions on the
documentation font being changed from serif to sans-serif. This would
only affect the web-based docs, not the ones being prepared for print.

An example of this is at
http://tau.devrandom.co.uk/issyl0/en_US.ISO8859-1/books/handbook/ ,
and a diff of my very simple changes is at
http://tau.devrandom.co.uk/issyl0/docs_font.diff

In my opinion, it makes a hugely positive difference and modernises
the look of the documentation set.


Agreed.  Actually, the new version really doesn't look different to me 
because my browser has been set to use sans-serif fonts for most things 
for years.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Changing the documentation's font style.

[Warren Block]

On Fri, 12 Apr 2013, Erich Dollansky wrote:


Hi,

On Fri, 12 Apr 2013 10:41:46 +0100
Isabell Long  wrote:


Hi all,

I sent this idea to the #bsddocs IRC channel a few days ago and no-one
there objected, but here you go. I'd like to know your opinions on the
documentation font being changed from serif to sans-serif. This would
only affect the web-based docs, not the ones being prepared for print.

An example of this is at
http://tau.devrandom.co.uk/issyl0/en_US.ISO8859-1/books/handbook/ ,
and a diff of my very simple changes is at
http://tau.devrandom.co.uk/issyl0/docs_font.diff

In my opinion, it makes a hugely positive difference and modernises
the look of the documentation set.


how old are you?

The serif fonts are easier to read for older people.

I agree, it looks more modern. But what is the idea behind a
documentation? Look good or being read by people for the content.


Try viewing the two versions in side-by-side windows.  The serif fonts 
were a lot blobbier and less sharp for me.  Aliasing and antialiasing at 
work with limited resolution.


Serif is easier to read in print, but that's much higher resolution.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Changing the documentation's font style.

[Warren Block]

On Sun, 14 Apr 2013, Isabell Long wrote:


The reason I specified Verdana in the beginning was to have some
familiarity between the website font and the documentation font -
before (and now) I think it looks disjointed. I have just made
font-family sans-serif without a specific default font, however. I've
kept the font-size specified as it makes for a nicer, smaller and less
huge and potentially daunting reading experience (to new users).


Doesn't that depend on the user's browser and screen resolution?  We 
have to assume that the reader is the one best qualified to decide what 
font size they need.


How's 
http://tau.devrandom.co.uk/issyl0/en_US.ISO8859-1/books/handbook/ now, 
as a compromise?


Okay, but could you do another without a set font size?
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Changing the documentation's font style.

[Warren Block]

On Sun, 14 Apr 2013, Isabell Long wrote:


Hi,

On 14 April 2013 16:57, Warren Block  wrote:

On Sun, 14 Apr 2013, Isabell Long wrote:

How's http://tau.devrandom.co.uk/issyl0/en_US.ISO8859-1/books/handbook/
now, as a compromise?


Okay, but could you do another without a set font size?


Sure. This is with just sans-serif, no font size set.
http://tau.devrandom.co.uk/issyl0/en_US.ISO8859-1/books/developers-handbook/


Thank you.  That looks fine to me.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

The doc lounge at BSDCan 2013

[Warren Block]

BSDCan 2013 will be held at the University of Ottawa in May.

During the nights of the conference, the FreeBSD documentation team will 
be hosting a "doc lounge", similar in concept to the traditional "hacker 
lounge" but aimed at improving FreeBSD documentation.


We plan to commit patches, update docs, and work on things that need to 
be done for the print edition of the Handbook. Anyone interested in 
getting a specific documentation problem fixed, or wanting to get 
started with the documentation tools or processes in general is 
encouraged to come and see us.


The doc lounge will be held each night from 18:30 to 21:00, in a series 
of rooms:


May 15 MRT221
May 16 UCU206
May 17 UCU301
May 18 MRT221

Hope to see you there!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [CFR] Migrating the documentation to a real XML toolchain

[Warren Block]

On Wed, 8 May 2013, Gabor Kovesdan wrote:

I've fixed all the reported problems again. (Except those that were already 
there before my work, since they are not trivial to fix in this phase.) I've 
also updated the generated documentation set:
http://people.freebsd.org/~gabor/db45/ 



Please let me know if you find more problems. I remind you again that the new 
generation process is quite different so there are differences in the 
rendering but please report only differences that you think that are 
problematic. We plan to merge back this changeset to head quite soon so that 
we can progress with further improvements and to avoid the maintenance cost 
of the branch.


HTML versions don't have a single/split HTML selection.



From the FDP:


"Last modified on 2013-02-18 bygabor." (missing space)
  ^^


From the Handbook:


The FreeBSD copyright and the trademarks are both shown as "Legal 
Notice" links.  I don't know if they should be shown inline as they were 
previously, but the links ought to have different names.


One other thing that jumps out is that  sections are in bold, 
while the rest of the  section is not bold.



I didn't see anything that was a serious problem.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [HEADSUP] Merging back the xml-tools branch

[Warren Block]

On Fri, 17 May 2013, Gabor Kovesdan wrote:


Em 16-05-2013 12:57, Gabor Kovesdan escreveu:
I'll be merging back the XML toolchain changes to head tomorrow around 6pm 
GTM. I'll temporarily lock head to avoid conflicting changes at the same 
time and head will be reopen very soon after the merge is complete. At the 
same time, the textproc/docproj port will be updated accordingly.
The merge is completed, Glen and I will be watching if everything went fine. 
You can continue working on documentation now, head is now open and make lint 
works again. Please run it before committing. If make lint passes, the build 
must succeed as well.


Worked for me last night.  Doing a 'make book.html' of the Handbook 
still ran tidy; wasn't that supposed to go away?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Committing Handbook updates

[Warren Block]

Please set me straight on how, when, and where to commit updates to the 
Handbook at present.


As I understand it, we are still in doc slush.  When is that planned to 
end?


Are small changes allowed, or should we save them for now?

There's the ISBN project branch.  Should we commit changes there now, so 
they'll be merged back when the branch is merged?


Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: 7.2.1.2 ...Flash...

[Warren Block]

On Wed, 22 May 2013, Dieter Lange wrote:

after "To install and enable this plugin:" IMHO text should better read 
"Compile and install" instead of just "Compile" (twice).


"Install" should be adequate.  There are also some small other issues 
there.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: 7.2.1.2 ...Flash...

[Warren Block]

On Wed, 22 May 2013, Warren Block wrote:


On Wed, 22 May 2013, Dieter Lange wrote:

after "To install and enable this plugin:" IMHO text should better read 
"Compile and install" instead of just "Compile" (twice).


"Install" should be adequate.  There are also some small other issues there.


Changes committed.  Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Upgrading to DocBook 5.0

[Warren Block]

On Tue, 28 May 2013, Gabor Kovesdan wrote:


I have a patch to preview how it would look like:
http://kovesdan.org/patches/fbsd-docbook5.diff

Please comment on this. It is very important to discuss this kind of changes.


I think that keeping up with DocBook versions is important.

Leaving out the systemitem class simplifies markup.  One nice thing 
about those classes is that they remove ambiguity during editing. 
Without them, it may be difficult to tell from context whether a 
systemitem is a username or a directory name, for example.  Although if 
that is not clear from context, it suggests the text needs improvement.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: removing 'changes' section from the online edition

[Warren Block]

On Sat, 1 Jun 2013, Gabor Kovesdan wrote:


Em 01-06-2013 18:26, Eitan Adler escreveu:

The Preface has a few sections 'Changes from the  Edition' which
enumerate changes made between print editions of the book.  I would
like to drop them from the online edition as they offer little value
and are right at the start of the handbook ('prime real estate').

They can be retained in the print edition where they offer a little more 
value.


Does anyone see a reason to keep them in the online version?
No objection from me, I just want to bring it up again that handling these 
with a single-source solution would be nice, i.e. using DocBook profiling. It 
would also facilitate merges. This basically consists of adding 
edition="print" to the affected section of preface and then setting up 
profiling. (I can do it, just ping me if there is consensus on this).


Yes!  I was just talking about this elsewhere.  Could we do it so only 
the non-print sections need to be modified?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: removing 'changes' section from the online edition

[Warren Block]

On Sat, 1 Jun 2013, Gabor Kovesdan wrote:


Em 01-06-2013 20:52, Warren Block escreveu:
No objection from me, I just want to bring it up again that handling these 
with a single-source solution would be nice, i.e. using DocBook profiling. 
It would also facilitate merges. This basically consists of adding 
edition="print" to the affected section of preface and then setting up 
profiling. (I can do it, just ping me if there is consensus on this).


Yes!  I was just talking about this elsewhere.  Could we do it so only the 
non-print sections need to be modified? 
You only need to add edition="online" to non-print sections. And only need to 
add edition="print" to non-online sections. The rest is shared and the markup 
is kept minimal.


How do you control which is included when the document is built?
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

print edition (was Re: removing 'changes' section from the online edition)

[Warren Block]

On Sun, 2 Jun 2013, Gabor Kovesdan wrote:


Em 02-06-2013 00:13, Warren Block escreveu:

On Sat, 1 Jun 2013, Gabor Kovesdan wrote:


Em 01-06-2013 20:52, Warren Block escreveu:
No objection from me, I just want to bring it up again that handling 
these with a single-source solution would be nice, i.e. using DocBook 
profiling. It would also facilitate merges. This basically consists of 
adding edition="print" to the affected section of preface and then 
setting up profiling. (I can do it, just ping me if there is consensus 
on this).


Yes!  I was just talking about this elsewhere.  Could we do it so only 
the non-print sections need to be modified? 
You only need to add edition="online" to non-print sections. And only need 
to add edition="print" to non-online sections. The rest is shared and the 
markup is kept minimal.


How do you control which is included when the document is built? 
There's an XSLT stylesheet provided by DocBook that preprocesses the markup 
and only leaves in the corresponding content. This is not enabled by default, 
only if you set it up with a knob in the Makefile of the actual document.


I'd like to try an actual test on the Handbook.  Is that feasible with 
what we have currently?  What specific changes need to be made to the 
Makefiles?


Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

RFC: Storage/Adding Disks rewrite

[Warren Block]

Many of the sections in the Storage chapter are very outdated.  Here is 
a rewrite of the Adding Disks section:


original version:
  http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/disks-adding.html

new version:
  http://wonkity.com/~wblock/addingdisks/disks-adding.html
  diff: http://wonkity.com/~wblock/addingdisks/handbook-disks-adding.diff

Changes:

SATA rather than SCSI
GPT rather than MBR (and a link to Wikipedia GPT ref)
gpart rather than fdisk/bsdlabel
no sysinstall
no dedicated mode

It is much shorter than the original, and has far less distractions like 
the numerous problems of MBR.  Because it is a fairly big change, I'd 
like to get feedback on the various outrages it may commit in terms of 
completeness, justice, or, well, anything.


One possible addition as a new section would be complete setup of a new 
disk for the operating system, incorporating some of the content that is 
now at http://www.wonkity.com/~wblock/docs/html/disksetup.html .  I'd 
envision that as a mostly-commands section, and think it would follow 
this simple introduction well.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

RFC: Profiling and merging for the print edition

[Warren Block]

My proposal for merging the ISBN branch and getting out of our
two-branch problem.

First, profiling works.  A demo file of the Porter's Handbook is here:
http://wonkity.com/~wblock/profiledemo/

After applying the patch, build either the online or print version of
the book with:

  make EDITION=online clean book.html
  make EDITION=print  clean book.html

The "online" version includes all sections with edition="online" or an
edition not set.

The "print" version includes all sections with edition="print" or an
edition not set.

Actually, all we need to mark are the online (non-print) sections.  By 
default, all sections would be for the print edition unless marked as 
online.


(Difficulties: the default edition should be set in the Makefile, and
make needs to recognize that changing the EDITION setting means the
files need to be rebuilt.  Left as an exercise for the reader.)

Given that we can do all or nearly all that needs to be done for the
print edition of the Handbook with profiling, I propose the following
merge plan:

Immediately merge the ISBN branch to head

Start using profiling in the entire Handbook

When ready to print the book:

  branch ISBN

  in the branch, make only the changes absolutely needed for print
  that cannot be done with profiling

  print the book

  the ISBN branch becomes historical, no new changes are merged to
  it

The first merge back from ISBN will be painful.  I think, that if I and
others pitch in, we can do this merge.  And of course, it only gets
worse as time goes on and there are more conflicts between the branches.
After that, things become much easier.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

RFC: acronym tags

[Warren Block]

The FDP writing guide says:

  The first three uses of an acronym should be enclosed in acronym tags,
  with a role attribute with the full term defined. This allows a link
  to the glossary to be created, and for mouseovers to be rendered with
  the fully expanded term.

I believe this is obsolete.  The current usage is to tag every 
occurrence of an acronym, but not enter the definition in the role 
attribute.  AFAIK, we've never used these to generate the glossary or 
mouseover links.


My suggestion is to make the current usage the preferred style:
1. Tag each occurrence of an acronym.
2. Do not enter the role= attribute.  These could result in differing 
definitions for the same acronym.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Profiling and merging for the print edition

[Warren Block]

On Fri, 21 Jun 2013, Hiroki Sato wrote:


Warren Block  wrote
 in :

wb> My proposal for merging the ISBN branch and getting out of our
wb> two-branch problem.
wb>
wb> First, profiling works.  A demo file of the Porter's Handbook is here:
wb> http://wonkity.com/~wblock/profiledemo/
wb>
wb> After applying the patch, build either the online or print version of
wb> the book with:
wb>
wb>   make EDITION=online clean book.html
wb>   make EDITION=print  clean book.html
wb>
wb> The "online" version includes all sections with edition="online" or an
wb> edition not set.

Please do not add a separate make variable for that.  We already have
FORMATS, and setting profiling variables (profile.attribute and
profile.value in XSLT) based on it should work.


You mean a new format should be added, like "pdf-withoutonline"?  That 
sounds like a better option.



Also, we should consider/discuss what kind of difference we need
actually and should allow between the two first.  Basically I am
against marking up everything with "online" or "print" because it
just makes the source files complicated.  I think it is useful only
for separating lengthy preface, edition history, and pgpkey list from
the body in book.xml.


Agreed.  The experiment showed that only sections which should not be 
included in the printed book could be marked with edition="online". 
All other sections would be left with edition unset.


There is a complication.  Links to sections which have been eliminated 
by profiling will break, so those would also need profiling.  I don't 
know how big an issue that will be, but suspect it will not be very 
much.


Hopefully, the profiling will be unobtrusive enough so that it can be 
done in head.  That will make turnaround time for the next printed 
version of the Handbook much shorter.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

RFC: Handbook Storage chapter RAID section removal

[Warren Block]

The Handbook Storage chapter has a section called RAID that describes 
the use of ccd(4) and ataraid(4).


ccd(4) is obsolete, having been replaced several times by newer drivers. 
I think ataraid(4) has been supplanted by graid(8).


So I propose to remove that RAID section entirely.  Yes, people may 
still be using these devices.  But we should not be recommending them to 
new users.


If you have a reason that should not be done, speak now.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Handbook Storage chapter RAID section removal

[Warren Block]

On Thu, 20 Jun 2013, Allan Jude wrote:


On 2013-06-20 14:20, Warren Block wrote:

The Handbook Storage chapter has a section called RAID that describes
the use of ccd(4) and ataraid(4).

ccd(4) is obsolete, having been replaced several times by newer
drivers. I think ataraid(4) has been supplanted by graid(8).

So I propose to remove that RAID section entirely.  Yes, people may
still be using these devices.  But we should not be recommending them
to new users.

If you have a reason that should not be done, speak now.


Since gmirror and graid are already covered in the GEOM chapter, that
probably makes sense. Organizationally, there seems to be a mix of where
the information is. Should all of the GEOM stuff be in the Storage
chapter, or should GEOM stuff like gbde and geli be moved from Storage
to GEOM?


Long-term, I'd like to reorganize by subject and try to eliminate some 
of the duplication we have now.  Before that, it would be good to trim 
as much obsolete material as possible.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Profiling and merging for the print edition

[Warren Block]

On Thu, 20 Jun 2013, Gabor Kovesdan wrote:


Em 20-06-2013 19:03, Warren Block escreveu:


There is a complication.  Links to sections which have been eliminated by 
profiling will break, so those would also need profiling.  I don't know how 
big an issue that will be, but suspect it will not be very much. 

Two proposed solutions:
1, The reference is often the last sentence of a paragraph, i.e. "For further 
informations on foo, please refere to bar." This can be just put into a 
profiled phrase.
2, Or if the reference has a longer explanatory text, it can have its own 
para with a profiling attribute.


Right.  My example showed the use of that.  I just did not want to 
oversimplify.  There is a little more work than just setting an edition 
on the sections to be removed for print.  However, I think it is 
manageable.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

RFC: Handbook Storage chapter floppy backup section removal

[Warren Block]

Continuing with the project to remove stuff from the Storage chapter 
that is long overdue...


The Backups to Floppies section has been warning that floppies are not 
suitable backup media for a decade now.  New machines have not included 
floppy drives for a long time.  It's time for this section to be 
retired.


I plan to remove this at the same time as the RAID section (ccd(4) and 
ataraid(4)).

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Handbook obsolescence scan: "The vinum Volume Manager"

[Warren Block]

Next on the list of potentially outdated things in the Handbook: "The 
vinum Volume Manager", a whole chapter on vinum.  Actually, it is really 
now about gvinum.


Are there any situations where new users should be advised to use gvinum 
rather than ZFS or gconcat/gstripe/gmirror?


What reasons are there for this chapter to remain in the Handbook given 
the newer, simpler alternatives?


If the information should remain, why should it be separate from the 
GEOM chapter?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Handbook obsolescence scan: "The vinum Volume Manager"

[Warren Block]

On Tue, 25 Jun 2013, Frank Leonhardt wrote:


On 25/06/2013 16:43, Warren Block wrote:
Next on the list of potentially outdated things in the Handbook: "The vinum 
Volume Manager", a whole chapter on vinum. Actually, it is really now about 
gvinum.


Are there any situations where new users should be advised to use gvinum 
rather than ZFS or gconcat/gstripe/gmirror?


What reasons are there for this chapter to remain in the Handbook given the 
newer, simpler alternatives?


If the information should remain, why should it be separate from the GEOM 
chapter?


I remember reading this and the gmirror stuff at the same time and wondering 
what it was all about. Whilst I'm generally not in favour of chucking stuff 
out of a manual if it exists on the ground, at the very least this could do 
with a sanity warning. At the time I had no way of knowing whether one method 
or the other was deprecated. I suppose I made a lucky guess.


That is exactly the problem with old information.  gvinum still works, 
but there is little reason to recommend it over the newer solutions.


Rather than just removing this chapter, it could be converted to a 
separate article, along with an added introduction about when it was 
removed from the Handbook and why.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Handbook obsolescence scan: "The vinum Volume Manager"

[Warren Block]

On Tue, 25 Jun 2013, Frank Leonhardt wrote:

Couldn't agree more! In fact the whole disk mirroring thing still 
confuses me, as there are too many options and no guide for choosing 
between them. As far as I understand it, gmirror is the way to go in 
most cases because you end up with two identical drives, either of 
which can be salvaged from the wreckage after a crash, stuck in to 
another PC and booted. ZFS is the solution if you want to spread lots 
of data across lots of drives.


ZFS can do mirrors, too, and almost everything else.  Its weakness now 
is that it is relatively memory hungry.  So I would advise this:


gmirror(8) for data safety on machines with relatively limited memory.
graid(8) for software BIOS RAID.
ZFS for mirrors or more typical RAID arrays on machines with 4G of 
memory or more.


Actually, in practical terms, I don't see why ZFS is better than pairs 
(or threes) of gmirrored drives mounted on to one file system in the 
traditional way. Perhaps I just don't get it, or perhaps I'm just too 
traditional to give up on the idea that it's good to know which drive 
a particular file is on.


It's RAID, so you get more space than mirrors, and possibly better 
performance for some things.  ZFS RAID-Z1 (and -Z2, -Z3) have a lower 
vacuum coefficient than RAID-5.  There are lots of nifty features, like 
being able to add storage without reformatting.


There are other options, but I suspect the three above cover most of the 
needs and are what we should be suggesting to new users in the Handbook.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Handbook obsolescence scan: "The vinum Volume Manager"

[Warren Block]

On Tue, 25 Jun 2013, Benjamin Kaduk wrote:


On Tue, 25 Jun 2013, Warren Block wrote:

Next on the list of potentially outdated things in the Handbook: "The vinum 
Volume Manager", a whole chapter on vinum.  Actually, it is really now 
about gvinum.


Are there any situations where new users should be advised to use gvinum 
rather than ZFS or gconcat/gstripe/gmirror?


What reasons are there for this chapter to remain in the Handbook given the 
newer, simpler alternatives?


If the information should remain, why should it be separate from the GEOM 
chapter?


Hmm, I seem to recall there being desire to keep the documentation around the 
last time this question came up, but don't remember why.  Let's go rooting 
around in the archives...


It seems that as of 2009, gvinum was still useful enough that I was happy to 
have documentation fixes for it 
(http://lists.freebsd.org/pipermail/freebsd-doc/2009-May/015913.html), though 
just two weeks later this thread 
(http://lists.freebsd.org/pipermail/freebsd-hackers/2009-May/028730.html) 
sees to indicate that it was dying already.  The documentation is always 
behind on the times...


I thought there was an attempt to remove gvinum or the documentation thereof 
since then, but cannot find any record of it.  That means we don't get to 
re-analyze the arguments presented then, and can just do it.


Moving it to an article should cover all the bases.  It won't be 
first-line information in the Handbook, but can still be found.  And 
eventually, if not already, we can have an archive section for obsolete 
information that may still be useful to someone, somewhere, but not most 
users.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Handbook obsolescence scan: "The vinum Volume Manager"

[Warren Block]

On Wed, 26 Jun 2013, Eitan Adler wrote:


On Wed, Jun 26, 2013 at 4:23 AM, Warren Block  wrote:

Moving it to an article should cover all the bases.  It won't be first-line
information in the Handbook, but can still be found.  And eventually, if not
already, we can have an archive section for obsolete information that may
still be useful to someone, somewhere, but not most users.


I find that articles are less often
- updated
- translated

so I think that "downgrading" the content to an article is a good step
if we think the information is not useful in the general case.

However, if the information is obsolete we already have
http://docs.freebsd.org/doc/ and it should be removed entirely.


I kind of wish you had pointed that out earlier today, before I made an 
article version of the vinum chapter.  It's ready to commit, but even 
easier to delete.


Speaking of that link: can it be found on from
http://www.freebsd.org/docs.html ?
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Fixing the man page for renice

[Warren Block]

On Sat, 6 Jul 2013, Frank Leonhardt wrote:

On 06/07/2013 16:28, Glen Barber wrote:

Thanks Glen - the "patch" business is what's putting me off! I'm sure once 
I've done it, nothing will stop me. Is there a page or *really simple* guide 
to doing it, that assumes nothing?


Assuming the source in is /usr/src:
  cd /usr/src/usr.bin/renice
  cp renice.8 renice.8.orig

Edit the new version as desired.  When done,
  cd /usr/src
  diff -u usr.bin/renice/renice.8.orig usr.bin/renice/renice.8 > ~/renice.diff

This is a bit easier if you use Subversion to check out the source.


I'm tempted to re-write the whole lot, but I'm successfully resisting.


The use of asides, "the affected processes will run only when nothing 
else in the system wants to", and "administrative fiats" make me 
twitchy.  It seems more complicated than necessary and could stand with 
some clarity improvements.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Fixing the man page for renice

[Warren Block]

On Sun, 7 Jul 2013, Frank Leonhardt wrote:


On 06/07/2013 22:19, Warren Block wrote:
  On Sat, 6 Jul 2013, Frank Leonhardt wrote:
On 06/07/2013 16:28, Glen Barber wrote:

Thanks Glen - the "patch" business is what's putting me off! I'm 
sure once I've done it, nothing will stop me. Is there a page or *really simple* guide to 
doing
it, that assumes nothing?


  Assuming the source in is /usr/src:
    cd /usr/src/usr.bin/renice
    cp renice.8 renice.8.orig

  Edit the new version as desired.  When done,
    cd /usr/src
    diff -u usr.bin/renice/renice.8.orig usr.bin/renice/renice.8 > 
~/renice.diff

  This is a bit easier if you use Subversion to check out the source.

I'm tempted to re-write the whole lot, but I'm successfully 
resisting.


  The use of asides, "the affected processes will run only when nothing else in the system 
wants to", and "administrative fiats" make me twitchy.  It seems more complicated
  than necessary and could stand with some clarity improvements.


Thank you so much for the "idiot's guide". It's exactly what I needed for the 
first time around.


I should have mentioned that the one to edit is renice.8, but maybe it 
was clear.


If Subversion was used to check out the source, just edit that file. 
When done, produce a patch with

  cd /usr/src
  svn diff usr.bin/renice/renice.8 > ~/renice.8.diff

Also, mdoc(7) is the reference for the mdoc macros.  Sadly, we don't 
have anything about it in the FDP Primer.



As to the language style, I was also worrying about things like "...can only 
monotonically increase...", but perhaps my memories of calculus are sub-par and it'd 
be as clear as day to
the rest of the world. I'm inclined to do a radical rewrite and a tweak and 
post them both here for the list to decide.


That would be great!  Thanks!___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Upgrading to DocBook 5.0

[Warren Block]

On Wed, 3 Jul 2013, Alberto Mijares wrote:

On Wed, Jul 3, 2013 at 3:56 AM, Gabor Kovesdan  wrote:

Em 24-05-2013 19:35, Gabor Kovesdan escreveu:


I'm working on upgrading our documentation set to DocBook 5.0 and I'd like
to discuss some details. We have some customizations and strange uses, which
can be expressed with DocBook 5.0's own vocabulary. This upgrade is a good
opportunity to change these, as well. I propose the following changes in our
vocabulary:


One more thing to discuss: shall we maintain the sect1, sect2, ... elements
or just use section? The section element can have another section element
embedded and the numbering in the rendered version is inferred by the level
of embedment. This is more uniform and less redundant. In own docs that I
write with DocBook I only use section and it works fine. Opinions?



IMHO, is a good thing to keep a visual clue of the level you are going
down while writing.


Yes, but that is what the indentation also does.


So,  should be kept, I think.


But it is another thing the user has to track.

The DocBook 5 book shows both forms.  Converting to  would be 
just a search and replace.  Do we need to pick one method before the 
DockBook 5 version merge?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: svn commit: r42201 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup

[Warren Block]

On Tue, 9 Jul 2013, Benjamin Kaduk wrote:

I have done my share of fitting relatively large font text into a small space 
and trying to get the wrapping to look nice; with a nbsp there will almost 
certainly be some font size+page width combinations that look bad.


We should probably discuss and decide one way or the other and actually put 
it in the word list, so we remember for next time.  I actually don't have 
strong feelings either way.


"Ports Collection" is there now.  Or do you mean nbsp in general?  I 
think the justification for using in "&os; 9.2" is that the version 
number is so narrow on its own that it would simply look bad if wrapped 
to the beginning of a line.  That's a guess, I don't recall any explicit 
justification.  As Gabor pointed out, it may not work or may even be 
contrary to what is desirable in translations.


I went back through the history of this file, and at least one instance was 
added in r33364 by pgj (cc'd), with review by gabor@, even!  That was back in 
Dec 2008, so changing our minds now would not be terrible, if we want to.


Does anyone want to argue for keeping the nbsp?


For "FreeBSD 9.2", numbers and units like "8 GB", and guibutton uses, I 
think using nbsp is probably okay.  For "Ports Collection" or other 
instances of multiple full words, I can't think of a compelling reason 
to use it.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: svn commit: r42201 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup

[Warren Block]

On Wed, 10 Jul 2013, Gabor Kovesdan wrote:


Em 10-07-2013 03:36, Warren Block escreveu:


For "FreeBSD 9.2", numbers and units like "8 GB", and guibutton uses, I 
think using nbsp is probably okay.  For "Ports Collection" or other 
instances of multiple full words, I can't think of a compelling reason to 
use it. 
Seems like a good rule of thumb. I agree on version numbers and units but 
what do you mean by guibutton uses? I remember of Cancel, OK and such but do 
we have two-word guibuttons?


nbsp is used to glue together the square brackets and the label:
  [ Save ]
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: svn commit: r42201 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup

[Warren Block]

On Wed, 10 Jul 2013, Gabor Kovesdan wrote:


Em 10-07-2013 13:19, Warren Block escreveu:
what do you mean by guibutton uses? I remember of Cancel, OK and such but 
do we have two-word guibuttons?


nbsp is used to glue together the square brackets and the label:
  [ Save ] 

And what if we don't use spaces at all? Would that look ugly?


There are some without the spaces and even without the brackets in the 
original 8.x install chapter of the Handbook.  The new form with the 
nbsp originated in the bsdinstall chapter.


To me, the new form is easier to read.  Unless there are complaints, 
I'll add it to the FDP Primer.  Kind of thought it was already in there, 
actually.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Upgrading to DocBook 5.0

[Warren Block]

On Sun, 14 Jul 2013, Gábor Kövesdán wrote:


Some more things:

- Admonitions (top, note, warning boxes) look quite strange in lists and such 
places. I think we should add a policy to avoid them and start changing the 
markup.


Admonitions are overused in some places.  They are visually jarring, 
often moreso than the tip or warning deserves.  A link to an example of 
this particular problem would be helpful to see what you mean, though.


- We extensively use markup in titles, which later renders with a different 
font. E.g. we mark the X of 9.X as replaceable or we mark up root as a 
username. I think that such rendering should be avoided in titles and the 
easiest and cleanest way to do so would be not using such markup in titles.


Please expand--what is the problem with differing fonts in titles?  I 
can see this both ways, but the text of a title being consistent with 
the rendering in the body seems like an advantage.


- Currently, we use the CALS table model in the documentation, while DocBook 
also supports the HTML table model. It has a more simple syntax and more 
rendering features in the DocBook stylesheets. Another advantage is that by 
using it, we would have only one table semantics in docs + web. Any objection 
to changing to the HTML table model?


An example would be useful here, also.  For compatibility with the rest 
of the world, we should probably stick with the most common usage.


- Some lists have their own title, while the preceding text usually 
introduces well what is enumerated in the list. I find the rendered title 
quite strange between this text and the list. Besides, I don't remember 
having seen technical books that use such titles. My suggestion is to simple 
remove them. Any objection or better idea?


Please give an example here, also.

All of these suggestions seem to be style changes that are not 
necessarily tied to the change to DocBook 5, or maybe changes that are 
not possible until after the conversion.  Unless they're required, it 
may be best to wait until after the conversion.___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: RFC: Upgrading to DocBook 5.0

[Warren Block]

On Sun, 14 Jul 2013, Gabor Kovesdan wrote:


Em 14-07-2013 14:52, Warren Block escreveu:

On Sun, 14 Jul 2013, Gábor Kövesdán wrote:


Some more things:

- Admonitions (top, note, warning boxes) look quite strange in lists and 
such places. I think we should add a policy to avoid them and start 
changing the markup.


Admonitions are overused in some places.  They are visually jarring, often 
moreso than the tip or warning deserves.  A link to an example of this 
particular problem would be helpful to see what you mean, though.

For example here: http://www.freebsd.org/doc/en/books/handbook/history.html

It breaks the list. It is even worse in PDF rendering since there are page 
boundaries and it breaks the page up to two parts.


I see what you mean.  But if we say "don't use admonitions in lists 
because they are visually ugly, that becomes markup for appearance and 
not for semantics.


Some tweaking of the CSS may help, like reducing the size of the 
admonition title so it is not so much larger than the surrounding text. 
docbook.css is something I've been meaning to look at, hopefully soon.


- We extensively use markup in titles, which later renders with a 
different font. E.g. we mark the X of 9.X as replaceable or we mark up 
root as a username. I think that such rendering should be avoided in 
titles and the easiest and cleanest way to do so would be not using such 
markup in titles.


Please expand--what is the problem with differing fonts in titles?  I can 
see this both ways, but the text of a title being consistent with the 
rendering in the body seems like an advantage.
Apart from the ugly visual outlook, it is not conventional in books and as 
such, it is just bothering and confusing for the reader. It breaks the 
information flow. Typographyc conventions serve for nice visual outlook and 
usability. The typesetting should facilitate reading and not difficulting it. 
If we want to publish a high-quality print edition of Handbook, we must 
follow the conventions, otherwise it won't be a serious publication.


Again, doesn't this break the semantics versus appearance separation? 
If the standard is to show titles in a single font and size, then that 
should be done when rendering.  Semantically, a filename is a filename 
whether it is in a title or body text.


I find different fonts for filenames and commands to be useful, even in 
titles.  The O'Reilly style guide doesn't mention anything about title 
styles, and in a quick search I did not find anything else.


- Currently, we use the CALS table model in the documentation, while 
DocBook also supports the HTML table model. It has a more simple syntax 
and more rendering features in the DocBook stylesheets. Another advantage 
is that by using it, we would have only one table semantics in docs + web. 
Any objection to changing to the HTML table model?


An example would be useful here, also.  For compatibility with the rest of 
the world, we should probably stick with the most common usage.
Most common is very relative. HTML uses exclusively the HTML table model, 
hence the name. CALS is older and quite common in the SGML/XML world. Both 
are supported in DocBook and we currently use CALS. Earlier there was no 
other option in DocBook. Using exclusively HTML tables would reduce the used 
table models to one.


Examples: just google for CALS table and HTML table, both are documented 
extensively.


For reference, here are links:

http://www.docbook.org/tdg5/en/html/cals.table.html
http://www.docbook.org/tdg5/en/html/html.table.html

Changing the source documents could be scripted, but would also require 
modifications to the FDP Primer.


I can't tell if HTML tables have all the same capabilities as CALS 
tables.


- Some lists have their own title, while the preceding text usually 
introduces well what is enumerated in the list. I find the rendered title 
quite strange between this text and the list. Besides, I don't remember 
having seen technical books that use such titles. My suggestion is to 
simple remove them. Any objection or better idea?


Please give an example here, also.

http://www.freebsd.org/doc/en/books/handbook/bsdinstall-pre.html

Look at 2.3.3.  There's a semicolon at the end of the last paragraph and list 
title is just floating there in the middle. This type of titles breaks the 
flow of the text and doesn't facilitate reading.


The previous toolchain rendered that title in bold:
http://docs.freebsd.org/doc/9.0-RELEASE/usr/share/doc/freebsd/en_US.ISO8859-1/books/handbook/bsdinstall-pre.html

Agreed, that title does not look very good.  Adding a colon to list 
titles when rendering would help.  Removing all list titles be too 
severe.


All of these suggestions seem to be style changes that are not necessarily 
tied to the change to DocBook 5, or maybe changes that are not possible 
until after the conversion.  Unless they're required, it may be best to 
wait 

Title formatting (was Re: RFC: Upgrading to DocBook 5.0)

[Warren Block]

On Sun, 14 Jul 2013, Gabor Kovesdan wrote:

I find different fonts for filenames and commands to be useful, even in 
titles.  The O'Reilly style guide doesn't mention anything about title 
styles, and in a quick search I did not find anything else.
Ok, it doesn't specify it explicitly but can you show me a technical book 
that has such titles? A real, published book, please, not online docs.


Mastering Regular Expressions (1998), by Jeffrey E. F. Friedl, shows 
acronyms in titles in a smaller all-caps size.  There is a Perl chapter 
with titles including "Modification with \Q and Friends: True Lies", 
"The /e Modifier", and "Using /g with a Regex That can Match 
Nothingness".  The "\Q", "/e", and "/g" in those titles are in a 
monospace typewriter font.  This is an O'Reilly book, but most of the 
other O'Reilly books I checked use the same font for all of the title.


C Programming, A Modern Approach (2008), by K. N. King, has a Loops 
chapter with section titles like "The while Loop" and "The do 
Statement", where "while" and "do" are in a monospace typewriter font.


Advanced Programming in the UNIX Environment (2001), by W. Richard 
Stevens, has section titles like "stat, fstat, and lstat Functions", 
"Streams and FILE Objects", and "pty_fork Function".  The keywords are 
in a monospace typewriter font.


UNIX System Administration Handbook (2001), by Evi Nemeth, shows 
keywords in the same font, but bold.  In "The /etc/ttys and /etc/ttytab 
files", the filenames are bold.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Project GRUDS: Handbook disk reorg

[Warren Block]

Project GRUDS (Grand Unified Disk Storage)

Goal: Edit and rewrite the scattered, repetitive, and conflicting Handbook
sections on disk storage into a unified group.  This would be a separate
 in the Handbook, starting where chapter 19, Storage, currently
begins.

The problem: Right now there are at least three different places in the
Handbook show disk partitioning methods and guidelines.  All are
different, and none really complete.  An in-depth chapter on
partitioning would allow sections to link to it and dispense with long
explanations that distract from the current topic.  Besides reducing
redundancy, this would make many sections shorter and let users familiar
with the concepts skip ahead easily.

It's a big project, but even as a plan would help future Handbook
contributions go in the right place.

Tentative outline:


Part 4:Disk Storage
  Introduction
Quick start
  links to current methods for
mirror (gmirror and ZFS)
BIOS RAID (graid)
RAID-5/RAID-Z (ZFS)

Disk Hardware Chapter
  Introduction
  Blocks
512-byte
Advanced Format
  Hardware RAID versus software RAID
Comparison, advantages and disadvantages
  HAST?
  Device names
SATA, IDE, SCSI, USB, most common hardware RAID device names
  Conclusion


Disk Partitions Chapter
  Introduction
  Partitioning Schemes
Metadata (types, locations, conflicts)
MBR
GPT
Others
  Conclusion


Labels Chapter (expanded from existing GEOM "Labeling Disk Devices")
  Introduction
easy device relocatability
provided by geom_label (others?)
  GPT labels
  Generic labels (glabel(8))
  Filesystem labels
  "Unique ID" labels
GPT UUID
ufsid
others?
  Conclusion


GEOM Chapter ("Disk Device Transformations with GEOM"?)
  Introduction
what is GEOM?
  from existing GEOM chapter
additional section on graid(8)
sorted in order of most common usage (gmirror, graid, ...)
  Conclusion


Filesystems Chapter
  Introduction
what are filesystems?
  UFS
traditional split-filesystem layout
newer, unified everything in root layout
  Other filesystems
ext2, NTFS, etc
mention NFS, with pointer to NFS section in "Network Servers"
mention ZFS, and how it is more than a filesystem, and will be
covered in the next chapter
  Conclusion


ZFS Chapter
  neither fish nor fowl, it's a dessert topping *and* a floor wax
  both device and filesystem
  Introduction
what is it?
brief mention of best capabilities
  in-depth
  Conclusion


Backup Chapter
  Introduction
  UFS Backup (main part from existing Storage chapter)
  ZFS Backup
  Conclusion
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Entities: DocBook versus XHTML

[Warren Block]

The FDP Primer, which I have been bludgeoning lately, has no section 
that really tells the basic FreeBSD-specific entities available, either 
in XHTML or DocBook or both.


The XHTML section does not show the correct way to refer to a Handbook 
chapter or an article.


&os; is only used a couple of times in the entire FDP Primer, and those 
are new, and I added them!


So please, let's collect a list of the most basic entities, and add it. 
I'm also curious to know why some but not all of the DocBook entities 
can be used in XHTML.



FreeBSD DocBook Entities
  Entity Name   Expands To
  
  &os;  FreeBSD
  &os.current;  FreeBSD-CURRENT
  &os.stable;   FreeBSD-STABLE
  &url.books.handbook;  ../../../..

Effectively, that last one works out to 
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook



FreeBSD XHTML Entities
  Entity Name  Expands To
  
  &base;   http://www.freebsd.org

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Project GRUDS: Handbook disk reorg

[Warren Block]

On Mon, 15 Jul 2013, Allan Jude wrote:


Notes:
Quick-start section should probably cover installation with 'root on zfs'


Excellent point!  We really need to make the quick start sections almost 
mandatory.  Added to outline.



Hardware chapter might mention SAS and things like SAS expanders and
other enterprise hardware considerations


Yes.  Added to outline.


The metadata storage location conflicts chapter is a really good idea.
whole-disk GEOM + GPT is basically not possible, so you get in to
per-partition GEOMs


There is a little section about this in the new RAID1 (gmirror) section.


The labels bit should probably talk a bit about ZFS gUIDs and how ZFS
does labels (this is both metadata and a label...) too


Added to outline.


The GEOM chapter should have at least a small stub for each GEOM type,
like cache, journal, multipath, etc


Agreed.  The hard part is getting people to write the missing ones.


For the ZFS chapter, this is the structure that bcr@ and myself proposed
at the last docsprint (this is probably a lot more detail than you need,
but if anyone has suggestions or ideas for additional things to do,
please let me know):

ZFS
   - ZFS introduction (what is ZFS)
   - ZFS Features and Terminology (giant table of definitions)


I have not really looked at the new section yet, but I did see the giant 
table.  Personally, I'd rather have a gentle introduction that builds 
up, and then definitions later.  It reminds me of instructions on 
recording menus for phone systems.  They said not to put the number 
first ("Press one for..."), because it gives people anxiety about 
remembering that number.  Instead, put the description first, then the 
thing to remember last: "For help, press one."  In computer terms, a lot 
of definitions I have to remember won't help me as much as an 
introductory section that says "ZFS storage devices, called *zpools*, 
can be a single disk or group of disks."  And then build on that. 
Later sections would have full detail and definitions.


Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Trouble building release with docs

[Warren Block]

On Sat, 20 Jul 2013, Daniel O'Connor wrote:


Hi,
I am trying to do a full (customised) release of 9.1 but I am having trouble 
building the docs. If I use NODOC it builds fine, but without that I get..
[andenes 7:04] /usr/src/release #/usr/bin/time make release BUILDNAME=$BUILDNAME
make -C /usr/src/release  BUILDNAME=9.1-GENESIS obj
make -C /usr/src/release  BUILDNAME=9.1-GENESIS ftp cdrom memstick
cd /usr/src/release/doc && make all install clean 'FORMATS=html txt'  
INSTALL_COMPRESSED='' URLS_ABSOLUTE=YES DOCDIR=/usr/obj/usr/src/release/rdoc
===> en_US.ISO8859-1 (all)
===> en_US.ISO8859-1/relnotes (all)
/usr/bin/grep '^' article.xml > article.parsed.xml.tmp
grep: article.xml: No such file or directory
*** [article.parsed.xml] Error code 2

Stop in /usr/src/release/doc/en_US.ISO8859-1/relnotes.
*** [all] Error code 1

Stop in /usr/src/release/doc/en_US.ISO8859-1.
*** [all] Error code 1

Stop in /usr/src/release/doc.
*** [reldoc] Error code 1

Stop in /usr/src/release.
*** [release] Error code 1

Stop in /usr/src/release.
   0.48 real 0.37 user 0.10 sys

There is article.sgml though.. I have installed textproc/docproj and I can 
build /usr/docs fine.


What does svn say about that file?

  % cd /usr/src/release/doc/en_US.ISO8859-1/relnotes/
  % svn stat

The article.sgml suggests a leftover file from an earlier /usr/src that 
was not removed before svn checkout.  That does not explain why 
article.xml is missing, though.  It is present on my 9-stable and 
8-stable checkouts.  Maybe a mixed or partial checkout?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Trouble building release with docs

[Warren Block]

On Sun, 21 Jul 2013, Glen Barber wrote:


On Sun, Jul 21, 2013 at 05:19:23PM +0930, Daniel O'Connor wrote:


On 21/07/2013, at 16:19, Glen Barber  wrote:


On Sat, Jul 20, 2013 at 04:44:56PM +0930, Daniel O'Connor wrote:

Hi,
I am trying to do a full (customised) release of 9.1 but I am
having trouble building the docs. If I use NODOC it builds fine,
but without that I get..


[...]

May I ask why 9.1?



Actually that's an excellent question :)

I though 9.1 was coming out not 9.2 but that is not correct.

So, if I rebuild with 9.2 checked out will the docs build?



Yes.


Depending on the use, just downloading the built documents from 
ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/ could be more 
effective.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

FDP Primer: emacs and vim

[Warren Block]

Multiple people have said the emacs configuration shown in the FDP 
Primer is outdated.  Of particular interest is the section at the end of 
the emacs chapter:


http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/psgml-mode.html


There is also a vim configuration shown in the Writing Style chapter on 
indentation, currently 12.3.3:


http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style-guide.html

That also looks outdated (sgml rather than xml).


The proposal is two parts:

First, remove the "Using sgml-mode with Emacs" chapter altogether. 
Teaching users to use an editor is out of scope of the FDP Primer. 
(And reputed to be outdated, but so far emacs users have not volunteered 
to update it.)  This may have been a big deal back when it was added, 
but there are multiple XML-capable editors now, and their documentation 
will be more helpful to the user than a rarely-updated section in the 
FDP Primer.


Second, move the small configuration file entries for both editors into 
a new "Editor Configuration" appendix.  This will be easier for users to 
find and easier to keep updated.



So: emacs users, please provide a modern configuration for emacs.
vim users, provide an updated configuration for vim.


Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: CFR: documentation rendered in PDF with FOP

[Warren Block]

On Tue, 23 Jul 2013, Gabor Kovesdan wrote:

I'm working on new rendering solutions for our documentation. One renderer 
will be dblatex, which doesn't depend on Java but doesn't give such high 
quality output. The other one will be FOP, which is written is Java but 
produces better quality.


Here are some PDFs for review, rendered with Apache FOP:
http://kovesdan.org/files/fop/

I need suggestions for royalty-free print-quality Bengali, Greek and Cyrillic 
fonts since these are still not customized and the default fonts lack 
non-Latin glyphs.


Apart from this, any comments are welcome. I know some parts still need 
improvements but feel free to comment on anything you think that should be 
changed.


Thanks for your work on this!

In a quick look, I did not notice any obvious problems.  What are the 
quality problems with dblatex?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: CFR: documentation rendered in PDF with FOP

[Warren Block]

On Tue, 23 Jul 2013, Gabor Kovesdan wrote:


Hi,

I'm working on new rendering solutions for our documentation. One renderer 
will be dblatex, which doesn't depend on Java but doesn't give such high 
quality output. The other one will be FOP, which is written is Java but 
produces better quality.


Here are some PDFs for review, rendered with Apache FOP:
http://kovesdan.org/files/fop/

I need suggestions for royalty-free print-quality Bengali, Greek and Cyrillic 
fonts since these are still not customized and the default fonts lack 
non-Latin glyphs.


Apart from this, any comments are welcome. I know some parts still need 
improvements but feel free to comment on anything you think that should be 
changed.


There is something weird about bulleted lists and sub-lists, starting on 
page 35 of the PDF Handbook (page 7-9 of the content).  Some entries in 
the first list are blank, the ones in the second list have an extra 
linefeed after the bullet.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: CFR: documentation rendered in PDF with FOP

[Warren Block]

The line-wrap characters are very welcome!  They still need some tuning 
(see PDF page 26).  Or maybe that's in the source XML, but it's good to 
see a start on that!

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

screen elements and userinput in XHTML

[Warren Block]

In XHTML documents, our current CSS stylesheet does not distinguish 
between user-typed input and system output.  That's my fault, Gabor had 
user input in bold but I felt it had so much contrast that it distracted 
rather than clarified.  Our screen elements are not separated from other 
text, either.


The current programlisting elements are better, in a box with a gray 
background.  We could make screen elements identical, but there is some 
value to the reader in making them look different.


I checked various web documentation pages for other projects, and most 
did not distinguish between system output and user input.  In some 
cases, that is likely to prompt a user to type a prompt.  The 
best-looking example I found was some Slackware documentation, which 
uses plain text for system output and bold for user input, but put it on 
a gray background which helped tone down the contrast.


Putting this all together, I've been trying this experimental addition 
to doc/share/misc/docbook.css.  It makes the userinput bold, draws a box 
around screen elements, but uses a sort of medium tan background so it 
does not look like a programlisting.


The color is questionable, and there may be a better choice.  Lighter 
colors seemed too bright.  But I do find this easier to read.


Comments welcome.


Index: docbook.css
===
--- docbook.css (revision 42404)
+++ docbook.css (working copy)
@@ -240,6 +240,10 @@
white-space: pre;
font-family: monospace;
padding: 1ex;
+   background-color: #ec8;
+   border: 1px solid #ccc;
+   border-radius: 6px;
+   line-height: 1.1;
 }

 div.programlisting {
@@ -340,7 +344,7 @@
 }

 .userinput {
-   font-weight: normal;
+   font-weight: bold;
 }

 pre.screen strong {Index: docbook.css
===
--- docbook.css (revision 42404)
+++ docbook.css (working copy)
@@ -240,6 +240,10 @@
white-space: pre;
font-family: monospace;
padding: 1ex;
+   background-color: #ec8;
+   border: 1px solid #ccc;
+   border-radius: 6px;
+   line-height: 1.1;
 }
 
 div.programlisting {
@@ -340,7 +344,7 @@
 }
 
 .userinput {
-   font-weight: normal;
+   font-weight: bold;
 }
 
 pre.screen strong {
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: CFR: documentation rendered in PDF with FOP

[Warren Block]

On Wed, 24 Jul 2013, Gabor Kovesdan wrote:


On 2013.07.23. 23:11, Warren Block wrote:

There is something weird about bulleted lists and sub-lists, starting on 
page 35 of the PDF Handbook (page 7-9 of the content).  Some entries in the 
first list are blank, the ones in the second list have an extra linefeed 
after the bullet. 
It is a known issue and is actually the result of misplaced indexterms, not a 
bug in the rendering. I've already fixed some of them in the English docs but 
translations still has to be fixed and there may be slightly different cases, 
which I haven't caught yet. We should document in fdp-primer that indexterms 
should be put right inside of the text after the referred word. Not between 
paragraphs, not into , not into  but right inside 
 after the referred word without leaving a single a space. If they are 
not in , it can cuase such problems. And if you put a space before the 
indexterm, there may be a page break and you get a wrong page number in the 
index. But the probability of this latter is very low, the former thing is 
more important.


Presently, indexes and indeterms are not even mentioned in the FDPP. 
I'll start a list of things to add after the doc slush.  If you or 
anyone else have found things which are not documented well or at all in 
the FDPP, please let me know or enter a PR.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

and other tag usage

[Warren Block]

When writing  sections, I've generally not used other markup 
inside those sections except for .  For example:


  rm /tmp/foo

However, there are some spots in the Handbook where  tags are 
also used:


  rm /tmp/foo

This looks different in the XHTML output, with the filename rendered in 
green.


I feel that the first form is correct, we are pointing out what the user 
should type, but can see benefits for the second.  I have not counted to 
see which form is prevalent, but think it is the first.  The FDP Primer 
actually uses a filename without filename tags in the  
example.


Anyone care strongly either way?
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Another CSS suggestion: pre-wrap

[Warren Block]

Long lines in screen and programlisting elements run off the right side 
of the screen with the current CSS.


It would be great to have them wrap and include a visible a line wrap 
indicator, but that may not be possible, or may require Javascript.


Better than nothing is to have them at least have forced wrapping based 
on screen width.  That can be done with changes in div.screen and 
div.programlisting:


-   white-space: pre;
+   white-space: pre-wrap;

This seems to work well, other than there being no visible marker where 
a line is wrapped due to screen width.


Is there a better way to accomplish this?
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Another CSS suggestion: pre-wrap

[Warren Block]

On Sun, 28 Jul 2013, Gabor Kovesdan wrote:


On 2013.07.28. 19:45, Gabor Kovesdan wrote:

On 2013.07.28. 19:00, Warren Block wrote:
Long lines in screen and programlisting elements run off the right side of 
the screen with the current CSS.


It would be great to have them wrap and include a visible a line wrap 
indicator, but that may not be possible, or may require Javascript.


Better than nothing is to have them at least have forced wrapping based on 
screen width.  That can be done with changes in div.screen and 
div.programlisting:


-white-space: pre;
+white-space: pre-wrap;

This seems to work well, other than there being no visible marker where a 
line is wrapped due to screen width.


Is there a better way to accomplish this? 

This seems to work:
http://iany.me/2012/02/css-line-wrap-indicator/

The wrapping of programlisting content into span elements can be done in 
XSLT. 
This seems to does the XSLT-part, although it may be done in a better way 
since it breaks some DocBook features that we don't use:

http://kovesdan.org/patches/xhtml-wrap.diff


Nice!  Which DocBook features would be compromised?  Are there any other 
reasons not to start using this now?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Another CSS suggestion: pre-wrap

[Warren Block]

On Sun, 28 Jul 2013, Gabor Kovesdan wrote:


On 2013.07.28. 21:17, Warren Block wrote:
This seems to does the XSLT-part, although it may be done in a better way 
since it breaks some DocBook features that we don't use:

http://kovesdan.org/patches/xhtml-wrap.diff


Nice!  Which DocBook features would be compromised?  Are there any other 
reasons not to start using this now? 
Line numbering and syntax highlighting. Both require XSLT extensions and thus 
won't work with xsltproc. I don't know of any other reason not to use them.


Line numbering is nice sometimes, although sometimes it's easy to 
confuse with content.  Syntax highlighting could be useful in places 
like the Architecture Handbook, but as you say, we don't have it now.


Would you agree that using this line wrap now would not prevent 
switching to other methods in the future?


I think we should only use the indicator at the end of the line both not at 
the start of the wrapped part since this is more conventional. And it would 
be nice to use the same symbol that we use in the new PDFs. That is part of 
the Droid Sans Mono font. This example uses images but maybe it is possible 
to use text, I'm not sure about this, I don't know CSS so well. Anyway, we 
may as well create an image with an SVG editor.


Agreed on all counts.

A useful example is at the bottom of this page:

http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/xml-primer-elements.html

The xmllint output is huge and scrolls off the right of the screen.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Another CSS suggestion: pre-wrap

[Warren Block]

On Sun, 28 Jul 2013, Gabor Kovesdan wrote:


On 2013.07.28. 21:37, Warren Block wrote:


Line numbering is nice sometimes, although sometimes it's easy to confuse 
with content.  Syntax highlighting could be useful in places like the 
Architecture Handbook, but as you say, we don't have it now.


Would you agree that using this line wrap now would not prevent switching 
to other methods in the future?


I believe it is possible to make them work together. But using these 
extensions requires using Saxon as the XSLT processor, which is 
Java-based and slower than xsltproc.  Even if we end up using Java for 
PDF rendering, it would be better to keep the XHTML build fast and 
Java-free so that committers can easily test their work.


Do you mean Java is needed to do the linewrap on XHTML, or that it would 
be needed to do line numbers and syntax highlighting?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Another CSS suggestion: pre-wrap

[Warren Block]

On Mon, 29 Jul 2013, Gabor Kovesdan wrote:


On 2013.07.29. 0:09, Warren Block wrote:

On Sun, 28 Jul 2013, Gabor Kovesdan wrote:


On 2013.07.28. 21:37, Warren Block wrote:


Line numbering is nice sometimes, although sometimes it's easy to confuse 
with content.  Syntax highlighting could be useful in places like the 
Architecture Handbook, but as you say, we don't have it now.


Would you agree that using this line wrap now would not prevent switching 
to other methods in the future?


I believe it is possible to make them work together. But using these 
extensions requires using Saxon as the XSLT processor, which is Java-based 
and slower than xsltproc.  Even if we end up using Java for PDF rendering, 
it would be better to keep the XHTML build fast and Java-free so that 
committers can easily test their work.


Do you mean Java is needed to do the linewrap on XHTML, or that it would be 
needed to do line numbers and syntax highlighting?



For the latter two only.


Excellent!  What do you think about adding it after the doc slush ends 
in a week or so?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Another CSS suggestion: pre-wrap

[Warren Block]

On Mon, 29 Jul 2013, Gabor Kovesdan wrote:


On 2013.07.29. 0:21, Warren Block wrote:


Do you mean Java is needed to do the linewrap on XHTML, or that it would 
be needed to do line numbers and syntax highlighting?



For the latter two only.


Excellent!  What do you think about adding it after the doc slush ends in a 
week or so? 
Good. I think the slush is about content change so that translators can catch 
up so I personally I would not object if you wanted to do it earlier.


Okay.  If the end of line character is an image, that will have to be 
included in imagelib, with acompanying changes in doc.images.mk.  Or 
maybe there's a better way to do it, and make sure that image is 
included with every document.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [CALL FOR REVIEW] Upgrading to DocBook 5.0

[Warren Block]

On Fri, 2 Aug 2013, Gabor Kovesdan wrote:

3, A dblatex-based rendering toolchain. This toolchain is more limited. Its 
customization is more difficult and non-Latin text is not wrapped properly. 
Also, it fails with programlistings in tables so it cannot build the whole 
documentation set. This is a limitation that is explicitly listed in the 
dblatex documentation. This is a Java-free solution but it does not give us 
full support and such a high quality as FOP.

Some sample documents can be found here:
http://kovesdan.org/files/dblatex/


This looks pretty good.  There is a problem in that paragraphs are 
indented inconsistently.  See the Committer's Guide, "3.1 Introduction" 
for an example.  The first paragraph is not indented, following ones are 
indented.


Thanks for your work on this!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Updating translation workflow

[Warren Block]

We have some problems with our translation workflow, and updating it 
could make life easier for everyone.  Note that as an American, I barely 
speak English, so there may be misconceptions in the following.  Please 
correct me if necessary.


* Translators work too hard.  No automation, no assistance from the
  computer to see what needs to be translated, no reuse of
  previously-translated terms.  Because of this, updating translations
  after the English version changes can take a long time.

* Few new translators are willing to work that hard, so we are missing
  up-to-date translations to several important world languages.

* Separating whitespace and content patches makes it more difficult for
  writers to edit existing English documents.

The current workflow, such as it is, is very, very old.  Since it was 
created, new ways to translate have come about.  PC-BSD is using Pootle 
(textproc/pootle, http://pootle.translatehouse.org/) for their 
documentation: http://pootle.pcbsd.org/


I think we can use a combination of tools to work with our existing 
documents.  The workflow would be like this:


1. Use textproc/itstool to create a "strings to be translated" file
   (.pot) from an XML file.

2. Use pootle as a database to translate any of those strings that have
   not already been translated.

3. Use itstool to merge the translated strings back into the XML file.

4. Build the translated document (DocBook or XHTML) as normal.

The first difficulty I've found is that itstool does not like entities. 
It could be modified to accept them, but probably the more correct 
procedure for translations is to expand them before using itstool.  This 
would be more correct for translations, as it's been explained to me, 
because some languages modify nouns depending on how they are used.  (In 
other words, our use of entities can be English-centric.)


Is there an easy way to expand entities?
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Updating translation workflow

[Warren Block]

On Tue, 20 Aug 2013, Gabor Pali wrote:


Hi Warren,

On Mon, Aug 19, 2013 at 6:07 PM, Warren Block  wrote:

* Translators work too hard.  No automation, no assistance from the
  computer to see what needs to be translated


I am not sure of this.  A few years ago we seem to have a consensus on
an informal "API" that allows tracking untranslated changes [1].  This
was the %SRCID% tag placed in the translated files.  Using this tag,
one could generate nice stats about the work to do [2], and get the
diffs to work with.  At least, that is what I did for a few years...


Interesting!


no reuse of previously-translated terms.


I have maintained a vocabulary for the translation of commonly used
expressions [3] in the past.  So I was consistent with myself at least
:-P


Well, yes, but this appears to be manual and does not automatically 
translate the same strings that are found in other documents.  That is 
part of what the newer automated systems do.



[1] http://lists.freebsd.org/pipermail/cvs-doc/2008-June/018345.html
[2] http://people.freebsd.org/~pgj/checkupdate/fdp.nl.reminder.txt
[3] https://wiki.freebsd.org/HungarianDocumentationProjectVocabulary


I did find a patch for itstool that seems to be what is needed to add 
DTD support so entities are expanded.  I have not tested it yet.


https://gitorious.org/~gmcharlt/itstool/gmcharlts-itstool
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Updating translation workflow

[Warren Block]

On Tue, 20 Aug 2013, Gabor Pali wrote:


On Tue, Aug 20, 2013 at 4:13 PM, Warren Block  wrote:

Well, yes, but this appears to be manual and does not automatically
translate the same strings that are found in other documents.  That is part
of what the newer automated systems do.


Erm, I am a bit skeptic about this as nouns (and expressions) in
Hungarian may be conjugated; inserting them into a sentence would
require one to understand the original context of the word -- that is,
if some automated system could translate those words in case of such a
language, no humans would be required any more at all... :-)


I would think translations of larger strings ("This is an example of a 
FreeBSD system") would override translations of smaller strings 
("FreeBSD").


But it's not clear, and a test would help.  Certainly it can be made to 
work.  Other large projects are using these systems, with a lot of 
content translated.  Because of the translation database, rewrites or 
massive edits would force the translators to start over.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Updating translation workflow

[Warren Block]

On Tue, 20 Aug 2013, Gabor Kovesdan wrote:


Em 20-08-2013 19:10, Warren Block escreveu:

On Tue, 20 Aug 2013, Gabor Pali wrote:


On Tue, Aug 20, 2013 at 4:13 PM, Warren Block  wrote:

Well, yes, but this appears to be manual and does not automatically
translate the same strings that are found in other documents. That is 
part

of what the newer automated systems do.


Erm, I am a bit skeptic about this as nouns (and expressions) in
Hungarian may be conjugated; inserting them into a sentence would
require one to understand the original context of the word -- that is,
if some automated system could translate those words in case of such a
language, no humans would be required any more at all... :-)


I would think translations of larger strings ("This is an example of a 
FreeBSD system") would override translations of smaller strings 
("FreeBSD").


But it's not clear, and a test would help.  Certainly it can be made to 
work.  Other large projects are using these systems, with a lot of content 
translated.  Because of the translation database, rewrites or massive edits 
would force the translators to start over.


I've worked with Trados before (commercial CAT software) and there you can 
set up a match percentage limit. If the limit is met, you are offered the 
translation of the matching text but you are able to edit it. From the 
translations you write a dictionary file is created, which stores earlier 
translations, so as you progress, there is always a wider basis of 
translations to search for matches. I think using similar methods in FreeBSD 
would be very practical if we can find proper open source CAT tools.


As I understand it (imagine it, really), this is how Pootle works.

I agree with Warren that we should improve our workflow since it is 
really outdated. As for expanding the entities, I'm concerned that we 
may loose functionality so I'd prefer just handling entity references 
as plain text there and translating them in the entity files or 
something similar.


I think you mean expanding not-so-simple entities like &man.ls.1; would 
lose the functionality of it making a link to the man page.  I agree, I 
was only thinking of simple entities like &os;.


If entities were passed through unchanged, the translator would have the 
freedom to leave them unchanged or convert them to plain text if needed. 
But this means we need some other change to itstool, which currently 
chokes on entities.  The older xml2po has an option to keep entities:

  xml2po -k article.xml
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Updating translation workflow

[Warren Block]

  I think we can use a combination of tools to work with our existing 
documents.  The workflow would be like this:

  1. Use textproc/itstool to create a "strings to be translated" file
     (.pot) from an XML file.

  2. Use pootle as a database to translate any of those strings that have
     not already been translated.

  3. Use itstool to merge the translated strings back into the XML file.


I'm not quite sure here when we are putting back strings I guess we have to 
check again the meaning of the sentence.


Examples may help:

A German translation of a sentence:
http://pootle.pcbsd.org/de/pcbsd/translate.html?unit=461257

Gnome uses the .pot/.po files to translate their documentation. 
Instructions that are specific to translating documentation as opposed 
to programs are hard to find.  Possibly they don't make that distinction 
because the process is identical.  An example:


https://wiki.gnome.org/ReleaseNotes/Translating

And a sample of the German .po file for a document:
https://l10n.gnome.org/POT/gnome-user-docs.master/docs/gnome-help.master.de.po


What if we can have some rules for English documentation change?
For instance maybe limitation of changes in doc for one commit per day etc. I 
know English version needs to be updated very frequently and always needs 
modifications, improvements etc.
However if we can have some limitation of changes (I mean small changes like 
maybe couple of hundred lines that translators can follow immediately with 
ease) then it would be much
easier for translators and that would maybe help new translators join. Like 
asking them to work on small changes and review if necessary.

And of course automated tools would be nice addition to it.


Personally, I'd like to see fewer restrictions and much more automated 
help for everyone.  With the .pot/.po system, whitespace changes seem to 
no longer be a problem.  The web interface makes it much easier to get 
involved with translation, less intimidating for new translators and 
less work for experienced translators.


Also, there are many people with experience using that translation 
system, so there's less of a learning curve.


It could provide helpful experience if FreeBSD translators signed up for 
an account on the PC-BSD Pootle site and tried translating a few things 
there.


And there may be other CAT software that we could use.  Pootle is just a 
first possibility because PC-BSD is using it.  It may even be possible 
to share the "translation memory" between PC-BSD and FreeBSD, reducing 
the effort to get documents translated.___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Feedback wanted: wrapping long lines in HTML docs

[Warren Block]

HTML versions of our documents show long lines in  and 
 elements.  At present, these  lines run right out of 
the boxes they are in.  Some lines are very long.  An example in the FDP 
Primer is 473 characters:

http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/xml-primer-elements.html
(search for "example.xml:5")

We have at least two ways of improving this.  Long lines can be treated 
as they are in the PDF versions: the line is wrapped and an indicator 
character shows where it has been wrapped.  Cut and paste will still 
copy it as a single line.  Advantage: the entire contents of long lines 
are shown.  Disadvantage: readers may misunderstand the wrapping or wrap 
indicator as literal.


Another option is to add "overflow: auto" in the CSS.  Scroll bars will 
be added to the bottom of screen and programlisting elements with long 
lines.  Advantage: long lines are shown without wrapping. 
Disadvantage: the reader has to scroll to see the hidden part of long 
lines.



Which method should be preferred for HTML documents, and why?
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: 4.12 Binary Formats

[Warren Block]

On Thu, 29 Aug 2013, John Baldwin wrote:


On Wednesday, August 07, 2013 8:08:17 pm Hugh O'Brien wrote:

Hi there,

I'm a relatively long time user but was recently reading through the
handbook to see if there was anything I could learn when I found this
section:

http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/binary-

formats.html


It's an interesting read, but I must question the wisdom of including it in
this stage of the handbook, where users are still new to the system. It
stands apart from the more immediately practical knowledge in the previous
pages and might be better suited to a page on writing your own programs.

I just wanted to call attention to this,


This section should likely just be axed.  It was a Big Deal when FreeBSD 3.0
switched from a.out to elf, but FreeBSD has been an ELF-only system for over
a decade now.


Removed, ejected, and expunged in 42604.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Tweaks to the wait(2) manpage

[Warren Block]

On Sat, 14 Sep 2013, Konstantin Belousov wrote:


On Thu, Sep 12, 2013 at 04:43:46PM -0400, John Baldwin wrote:

I have some tweaks to the wait(2) manpage, in particular to the sections on
wait6() and idtypes.  I did also change two other places to use uppercase for
ID since that seems to be what we do in other pages.  The alternate rendered
text is below followed by the diff.  One structural change I chose to make was
using a tagged list for the non-standard idtypes.  Our manpages in general
prefer tagged lists to bullet lists for enumerations.  I left the list of
standard types as-is as it includes a fourth bullet point that would not have
an associated tag (though one could perhaps move that into the paragraph
introducing the list of standard types if a tagged list was desired).  I kept
reading this page as I was writing this e-mail and changed more bits to
attempt to be more consisent with existing paragraphs, etc.:

 The broadest interface of all functions in this family is wait6() which
 is otherwise very much like wait4() but with a few very important dis-
 tinctions.  To wait for exited processes the option flag WEXITED must be

I did not liked the introductory sentence above, but was not able to
formulate the idea better.  Specifically, I do not like the narrative tone,
and think that 'broadest' and 'distinction' should be expressed better.


Agreed about "broadest", it's hard to tell what that means.  How about:

  wait6() is the most general function in this family, differing from
  wait4() in these important ways:

  To wait for exited processes, the WEXITED option flag must be
  explicitly specified.  This allows waiting for processes which have
  experienced other status changes without having to also handle the
  exit status from terminated processes.

  Instead of the traditional rusage argument, the wrusage argument
  points to a structure defined as:

...
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Docbook: programlisting and screen

[Warren Block]

On Mon, 30 Sep 2013, Randy Pratt wrote:


I've noticed that trying to copy content from the rendered Handbook
from a browser does not retain the line breaks in some places.  This
occurs for material that are contained within a  or
 elements.

As an example, try to copy and paste some content from the section
30.6.5.5. for "An Example Stateful Ruleset" into a text editor.
(http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/firewalls-ipfw.html)

The result is the entire copied content is a single line which would
require a lot of tedious editing.  I've tried different browsers with
the same result.  I finally ended using the xml source to do the
copy.

I seem to remember being able to do a copy but it was probably
when sgml was used.  Is there some way to make it easier to copy
these sections?


Firefox on FreeBSD does this for me also.  Interestingly, IE on Windows 
copies and pastes that example fine.  Firefox does not, on either 
FreeBSD or Windows.  Midori on FreeBSD pastes it correctly.  Either a 
new Firefox bug, or maybe a default setting that changed?

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: ZFS docs from vBSDCon

[Warren Block]

On Tue, 29 Oct 2013, Allan Jude wrote:


Attached find a patch for the zfsupdate-201307 project branch of stuff I
wrote during the vBSDCon Doc Sprint

More coming soon


Commited.  I also worked through about the first third of the chapter in 
an edit.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Developers' Handbook on the web server

[Warren Block]

http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/index.html

The copyrights only go to 2010.

Also:

"Last modified on August 2000 by ."

That seems just a tad off.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Developers' Handbook on the web server

[Warren Block]

On Tue, 29 Oct 2013, Taras Korenko wrote:


On Tue, Oct 29, 2013 at 02:57:55PM -0600, Warren Block wrote:

...
Also:
"Last modified on August 2000 by ."
...

 may be simply fixed with:

Index: en_US.ISO8859-1/books/developers-handbook/book.xml
===
--- en_US.ISO8859-1/books/developers-handbook/book.xml  (revision 43072)
+++ en_US.ISO8859-1/books/developers-handbook/book.xml  (working copy)
@@ -16,7 +16,7 @@

The FreeBSD Documentation Project

-August 2000
+$FreeBSD$


  2000


Also added the missing copyright notices and committed it.  Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: TODO item: Add info on USB printers

[Warren Block]

Forgot to send this to the list also...

On Wed, 30 Oct 2013, Warren Block wrote:


On Wed, 30 Oct 2013, Juris Kaminskis wrote:


Some first trial to create better coverage for USB printing support in
FreeBSD documentation. There are some more chapters to revise but this is
definetly one:

10.3.1.4.1. Checking a Parallel and USB Printer

This section tells you how to check if FreeBSD can communicate with a
printer connected to a parallel or USB port.

To test a printer on a parallel port use /dev/lptN on a USB port use
/dev/ulptN::

Become root with su(1).

Send data to the printer.

If the printer can print plain text, then use lptest(1). Type:

# lptest > /dev/lptN

Where N is the number of the parallel port, starting from zero. For USB
port /dev/ulptN, N number identifies how many USB printers are connected,
if zero then one printer connected.

If the printer understands PostScript® or other printer language, then send
a small program to the printer. Type:

# cat > /dev/lptN

Then, line by line, type the program carefully as you cannot edit a line
once you have pressed RETURN or ENTER. When you have finished entering the
program, press CONTROL+D, or whatever your end of file key is.

Alternatively, you can put the program in a file and type:

# cat file > /dev/lptN

Where file is the name of the file containing the program you want to send
to the printer.

10.3.1.4.1.1. Testing printers with special wire protocols

Many printers use different wire protocols instead of PostScript®. To test
communication create a file first in a format printer understands. Many
variants exist use Ghostscript and/or foo2zjs to convert PostScript® files.

Example:

HP Laserjet M1120 uses XQX protocol http://foo2xqx.rkkda.com/

Install foo2zjs port (includes foo2xqx)

Create a test PostScript® file (any decent program will print a PostScript®
file). Foo2xqx converts pbmraw file into xqx format, thus first
convert PostScript®
file to pbmraw format:

gs -sDEVICE=pbmraw -sOutputFile=YourFileName.pbm YourFile

And convert outputfile to xqx wire:

foo2xqx YourFileName.pbm > YourFileName.xqx

Last check if something prints:

cat YourFileName.xqx > /dev/ulptN

You should see something print. Do not worry if the text does not look
right; we will fix such things later.


Is there someone who can help me to review this and put into documentation?
After that I will take a look what else requires update to cover USB
printing.


Thank you for working on this.  The entire printing chapter really needs a 
rewrite, and I've been meaning to write an outline for what a new printing 
chapter should cover.  In the meantime, please look at
http://www.wonkity.com/~wblock/docs/html/lpdprinting.html and see if it is 
adequate in the meantime.___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: TODO item: Add info on USB printers

[Warren Block]

On Mon, 4 Nov 2013, Juris Kaminskis wrote:



Thank you for working on this.  The entire printing chapter really 
needs a rewrite, and I've been meaning to write an outline for what a new 
printing chapter
should cover.  In the meantime, please look at
http://www.wonkity.com/~wblock/docs/html/lpdprinting.html and see 
if it is adequate in the meantime.


I am not sure I understand what should I do next from this. Can you let me know 
how can I contribute further?


I've done some preliminary work on a rewrite of the printing chapter. 
Can you look at the article above and see if anything important is left 
out?


Thanks!___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: ZFS Handbook Update

[Warren Block]

On Tue, 5 Nov 2013, Allan Jude wrote:


On 2013-11-05 00:08, Allan Jude wrote:

Attached find ~320 new lines and 87 modified lines of the ZFS chapter of
the FreeBSD Handbook that I wrote on the plane to and from the FreeBSD
20th Anniversary Party.

Note: this is for, and is a patch against, the projects/zfsupdate-201307
branch.


After talking with wblock on IRC, here is a version of the above patch
with all my nasty whitespace changes included (since this is an
untranslated project branch)


Yes.  Mixing whitespace and content changes in this chapter should not 
be a problem now because nobody is translating it yet.  Still, after 
this, let's avoid it.  igor can help by limiting tests to just content 
or just whitespace:


  igor -Rz chapter.xml | less -RS  (to just test content)
  igor -RZ chapter.xml | less -RS  (to just test whitespace)

That's a lower case "z" for content, upper case for whitespace.

Committed, with a few minor edits.  Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [HEADSUP] Merging DocBook 5.0 update

[Warren Block]

On Thu, 7 Nov 2013, Gábor Kövesdán wrote:


On 2013.11.07. 16:12, Gábor Kövesdán wrote:

Hi,

I will soon merge the DocBook 5.0 updates to head. The tree will 
temporarily be locked until the merge is done. I will send out another 
email I have finished.



The merge is done, head is now open again for commits.


Thanks for your work on this!

In HTML, programlistings used to be a div ( 
but are now .  Likewise for .  The 
existing CSS has no entries for this.


Userinput is also not bold, another CSS issue.

I can fix these in the CSS.  But should they be fixed there, or in the 
generation of the HTML?


Thanks!___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [HEADSUP] Merging DocBook 5.0 update

[Warren Block]

On Fri, 8 Nov 2013, Warren Block wrote:


On Thu, 7 Nov 2013, Gábor Kövesdán wrote:


On 2013.11.07. 16:12, Gábor Kövesdán wrote:

Hi,

I will soon merge the DocBook 5.0 updates to head. The tree will 
temporarily be locked until the merge is done. I will send out another 
email I have finished.



The merge is done, head is now open again for commits.


Possibly a related bug:

The [Split HTML / Single HTML] links in books are identical, both 
linking to the directory rather than to index.html and book.html.___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Problems with handbook/book.pdf.bz2

[Warren Block]

On Mon, 11 Nov 2013, Johannes Meixner wrote:


I've been alerted in #freebsd/freenode to the fact that a user had issues with
ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/handbook/book.pdf.bz2,
in which he'd only see # after extracting and opening the file with 
SumatraPDF.

I've been able to reproduce that with an up-to-date zathura from ports, and 
would
be glad if someone would be able to look into that matter or tell me what I 
might
missing here.


The toolchain just changed.  It looks like a missing font, and building 
documents locally shows the same problem.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [HEADSUP] Merging DocBook 5.0 update

[Warren Block]

On Tue, 12 Nov 2013, Gábor Kövesdán wrote:


On 2013.11.08. 16:58, Warren Block wrote:
In HTML, programlistings used to be a div ( but 
are now .  Likewise for .  The existing 
CSS has no entries for this.


Userinput is also not bold, another CSS issue. 

Fixed, thanks!

By the way, when was screen changed to have a dark red background? I remember 
there were some discussions about distinguishing them from programlisting but 
personally I don't like dark red since at the first sight it looks very 
similar to a warning admonition. The red color calls the attention too much.


August 13: http://svnweb.freebsd.org/doc?view=revision&revision=42538

It was supposed to be a light tan.  It reduces the contrast difference 
between screen output and bold user input.


I did test other light colors, and this one was the least bad.  But it 
would be great to find a better combination.  Some web sites show 
commands as white text on a black background, resembling a typical 
console session.  I did not test that.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: draft of proposed handbook info on bhyve and virtualization

[Warren Block]

On Thu, 14 Nov 2013, Dee Nixon wrote:


As promised back in September, the following page contains a draft
of some proposed additions to the FreeBSD handbook:

http://petitecloud.org/handbook.jsp

The proposed new sections concern bhyve, the new hypervisor that
is part of the base system of FreeBSD 10.


Please see the FDP Primer, particularly the writing style chapter:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/book.html#writing-style

I did not look at the proposal in depth, but did see a lot of "you" and 
"your".

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: What are the limits for FFS file systems? 10+ years out of date..

[Warren Block]

On Sat, 23 Nov 2013, John-Mark Gurney wrote:


Attached is a patch that bring this up to date..  This was written back
when we were using UFS1 w/ 32bit block addresses...  Things have changes
now that UFS2 is standard...

The big thing is listing the memory requirements for fsck as the main
limiting factor on FS size...

I've had Kirk review the patch, and he's fine w/ it...

Shall I just commit it?


fsck should be either &man.fsck.8; or fsck, depending 
on context.


There is a duplicated "the" in the first paragraph.  igor -Rz should be 
run on the patched file.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: What are the limits for FFS file systems? 10+ years out of date..

[Warren Block]

On Sun, 24 Nov 2013, John-Mark Gurney wrote:


Warren Block wrote this message on Sun, Nov 24, 2013 at 07:21 -0700:

On Sat, 23 Nov 2013, John-Mark Gurney wrote:


Attached is a patch that bring this up to date..  This was written back
when we were using UFS1 w/ 32bit block addresses...  Things have changes
now that UFS2 is standard...

The big thing is listing the memory requirements for fsck as the main
limiting factor on FS size...

I've had Kirk review the patch, and he's fine w/ it...

Shall I just commit it?


fsck should be either &man.fsck.8; or fsck, depending
on context.

There is a duplicated "the" in the first paragraph.  igor -Rz should be
run on the patched file.


This is a single reply, thanks to the three of you for reviewing the
patch.. it's now committed in r43236..

Oh, I did change a such as to e.g., and in doing so, I noticed an e.g.
w/o the trailing period...  wondering if we should be consistent and
add it?


The style guide says to avoid "e.g." (it's Latin, and typically from 
academic and scientific environments).  igor checks for the correct 
form, which is with both periods and followed by a comma.


'igor -Ry filename' will give style suggestions for several things, 
including e.g. and i.e. and some other abbreviations.


Personally, I prefer "like" when suggesting similarity.  It might be 
easier for translators.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: [HEADSUP] Merging DocBook 5.0 update

[Warren Block]

Some automated conversions in the FDP Primer had problems.   is not 
allowed inside , so some of the entities in the FreeBSD 
Entities table lost their markup.


Is there a better solution than using < and >?

Example:

  Usage:  The manual page for
  cp is &man.cp.1;.

The usage is supposed to show exactly what the user would enter.  This 
does not work:


  Usage:  The manual page for
  commandcpcommand
  is &man.cp.1;.

It gives:

element literal: validity error : Element tag is not declared in literal list 
of possible children
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: typo

[Warren Block]

On Tue, 26 Nov 2013, Alexander Oblovatniy wrote:


Hello,

There are couple of typos at page 4.9
Shells
.

Both foobar and foo.bar start with fo. By typing ., then pressing *Tab* again,

the shell is able to fill in the rest of the filename.



Both 'foobar' and 'foo.bar' start with 'foo' instead of 'fo'.


Agreed.  But that example is terrible.  I'm working on rewriting it.


Table 4.3 provides a list of common environment variables and their

meanings.



Actual table's name is 4.4.


...which should not be hardcoded in the text, anyway.  Fixed, thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: en/handbook/users: proposed corrections

[Warren Block]

On Tue, 26 Nov 2013, Taras Korenko wrote:


 Good day, doc@ folks.

 I'd like to introduce some corrections to handbook/users chapter.  However,
there might be moot points, so any comments will be appreciated.
 Thanks.


Thanks for working on this!  Comments inline below, preceded with WB: 
for easy location.


Index: en_US.ISO8859-1/books/handbook/users/chapter.xml
===
--- en_US.ISO8859-1/books/handbook/users/chapter.xml(revision 43253)
+++ en_US.ISO8859-1/books/handbook/users/chapter.xml(working copy)
@@ -78,8 +78,8 @@


  The user name is typed at the login:
-   prompt.  User names must be unique on the system as no two
-   users can have the same user name.  There are a number of
+	prompt.  User names must be unique on the system. 
+	There are a number of


WB: I agree with this simplification, and would like to take it even 
farther.  How about "Each user must have a unique user name."?


rules for creating valid user names, documented in
&man.passwd.5;.  Typically user names consist of eight or
fewer all lower case characters in order to maintain
@@ -91,9 +91,8 @@
Password


- Each account has an associated password.  While the
-   password can be blank, this is highly discouraged and
-   every account should have a password.
+ Each account has an associated password.  The password can be
+   blank, however this is highly discouraged.

WB: This makes me think of "Do not look into laser with remaining eye." 
Let's just remove the sentence about setting a blank password.



   

@@ -149,7 +148,7 @@


  By default &os; does not force users to change their
-   passwords periodically.  Password expiration can be
+   passwords.  Password expiration can be
enforced on a per-user basis, forcing some or all users to
change their passwords after a certain amount of time has
elapsed.

WB: Agreed, the original sentence is not very good.  How about "By 
default, passwords do not expire.", and then use "enabled" rather than 
"enforced" in the next sentence.


@@ -377,7 +376,7 @@
/usr/share/skel
   
   skeleton directory
-  &man.adduser.8; is a simple program for adding new users
+  &man.adduser.8; is a simple program for adding new users.
When a new user is added, this program automatically updates
/etc/passwd and
/etc/group.  It also creates a home
@@ -527,7 +526,7 @@

   When passed no options, aside from an optional username,
&man.chpass.1; displays an editor containing user information.
-   When the user exists from the editor, the user database is
+   When the user exits from the editor, the user database is

WB: good catch!

updated with the new information.

   
@@ -773,8 +772,7 @@
this limit too small may hinder a user's productivity as
it is often useful to be logged in multiple times or to
execute pipelines.  Some tasks, such as compiling a large
-   program, spawn multiple processes and other intermediate
-   preprocessors.
+   program, spawn lots of processes.

WB: "start" may be more clear than "spawn".


   

@@ -818,7 +816,7 @@


  The limit on the amount of network memory, and
-   thus mbufssbsizelimiting 
userssbsize, a user may consume in order to limit network
+   thus mbufssbsizelimiting 
userssbsize, a user may consume.  This can be generally used to limit 
network
communications.

   
@@ -960,7 +958,7 @@
 In this example, the argument to -m is a
   comma-delimited list of users who are to be added to the group.
   Unlike the previous example, these users are appended to the
-  group list and do not replace the list of existing users in the
+  group and do not replace the list of existing users in the
   group.

 
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: en/handbook/users: proposed corrections

[Warren Block]

On Thu, 28 Nov 2013, Taras Korenko wrote:


 There's a second lap, which includes received suggestions.


One note:

@@ -960,7 +957,7 @@
 In this example, the argument to -m is a
   comma-delimited list of users who are to be added to the group.
   Unlike the previous example, these users are appended to the
-  group list and do not replace the list of existing users in the
+  group and do not replace the list of existing users in the
   group.

s/do not replace the list of/do not replace/

Otherwise, looks good!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: en/handbook/users: proposed corrections

[Warren Block]

As before, notes marked with WB: below.

On Thu, 28 Nov 2013, Taras Korenko wrote:


 ... and the last (previously unnoticed) chunk follows:


Index: en_US.ISO8859-1/books/handbook/users/chapter.xml
===
--- en_US.ISO8859-1/books/handbook/users/chapter.xml(revision 43259)
+++ en_US.ISO8859-1/books/handbook/users/chapter.xml(working copy)
@@ -984,7 +984,7 @@

 There are several ways to do things as the superuser.  The
   worst way is to log in as root 
directly.
-  Usually very little activity requires root
+  Usually very little activity requires superuser privileges,

WB: s/Usually very/Very/

   so logging off and logging in as root,
   performing tasks, then logging off and on again as a normal user
   is a waste of time.
@@ -991,8 +991,8 @@

 A better way is to use &man.su.1; without providing a login
   but using - to inherit the root environment.
-  Not providing a login will imply super user.  For this to work
-  the login that must be in the wheel group.
+  Not providing a login will imply superuser.  For this to work

WB: "login" is what the other section referred to as a "user name". 
Although su(1) calls it a login, "user name" is less ambiguous.


+  the current user must belong to the wheel group.
   An example of a typical software installation would involve the
   administrator unpacking the software as a normal user and then
   elevating their privileges for the build and installation of
@@ -1016,10 +1016,10 @@

 Using &man.su.1; works well for single systems or small

WB: s/Using//

   networks with just one system administrator.  For more complex
-  environments (or even for these simple environments)
-  sudo should be used.  It is provided as a port,
-  security/sudo.  It allows for
-  things like activity logging, granting users the ability to only
+  environments

WB: s/environments/environments,/

+  sudo might be used.  It is available as a

WB: "might" will cause the user to ask "Why?"  How about "For more 
complex environments, sudo is useful."


+  security/sudo package or port.
+  sudo provides activity logging, granting users the 
ability to only
   run certain commands as the superuser, and several other
   options.
   
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: en/handbook/users: proposed corrections

[Warren Block]

On Fri, 29 Nov 2013, Taras Korenko wrote:


 Updated version of the second patch follows.


Looks good to me!


P.S.: the funniest thing is that contents of users chapter was integrated
 into basics chapter in r42953, users chapter was removed (again r42953),
 and reappeared after db5 merge, updated with new subchapter () still being excluded from the build.
 So, next, I am to adapt current two patches to the new location:
 basics chapter :-/


I thought some of that looked familiar.  My apologies, I just did a big 
whitespace cleanup to the basics chapter.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: en/handbook/basics: proposed corrections

[Warren Block]

On Sat, 30 Nov 2013, Taras Korenko wrote:


On Thu, Nov 28, 2013 at 04:59:30PM -0700, Warren Block wrote:

...

 ...
 So, next, I am to adapt current two patches to the new location:
 basics chapter :-/


I thought some of that looked familiar.  My apologies, I just did a big
whitespace cleanup to the basics chapter.


 /* Well, a $subject was changed a bit... */
 I'd like to introduce some corrections to "Users and Basic Account
Management" subchapter of "UNIX Basics" chapter of our Handbook.
 Patches, that follow, summarize all the previous discussion and add
lost chunk of text ("Becoming Superuser") to handbook/basics chapter.


It looks good to me, although I did not build-test it.  There is also a 
doc slush right now, where we are encouraged to avoid major changes.


If you want me to commit it when possible, please enter it as a PR.

Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Help requested for bhyve(8) mdoc markup

[Warren Block]

On Wed, 4 Dec 2013, Peter Grehan wrote:


Hi,

bcr@ suggested that I email this list to get some mdoc assistance for the 
bhyve(8) man page. Also, any content and grammar review is welcome and 
appreciated :)


The raw text is at

   http://people.freebsd.org/~grehan/bhyve_8-v0.2.txt


I will work on this later today.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: docs/184550: bc -q option not documented in man page

[Warren Block]

On Fri, 6 Dec 2013, Eitan Adler wrote:


On Fri, Dec 6, 2013 at 9:18 PM, Glen Barber  wrote:

On Fri, Dec 06, 2013 at 09:12:30PM -0500, Eitan Adler wrote:

all options should be documented.  An undocumented option is a bug.
If we don't want people using it we should document as such.



It is documented.

case 'q':
/* compatibility option */
break;


Source code is not documentation.  It it surprising to hear that,
especially on this list.


This is a bit puzzling.  If -q is secret somehow, let's take it out of 
the synopsis.  If it's real, it should be in the synopsis and 
description.


  -qNo-op, does nil, nothing, nada.  Emphatically not for
compatibility with GNU bc, but coincidentally allows scripts
from icky other platforms where -q does something to run without error.
May occasionally print "gravy-sucking pig-dog" or contain traces
of soy, nuts, eggs, titanium, and riboflavin, all part of a
really interesting alibi.
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: Updates to the Uses section (twisted) in the porter's handbook

[Warren Block]

On Sun, 8 Dec 2013, Marcus von Appen wrote:


Dear doc@ people,

find attached a minor patch for the Uses section (a brief entry for
twisted) and a minor cleanup of the zope leftovers.


Modified version committed.  Thanks!
___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"

Re: en/handbook/basics: proposed corrections #2

[Warren Block]

On Thu, 12 Dec 2013, Taras Korenko wrote:


 Good day, doc@ folks.

 The following notes were made while working on translation of "Users
and Basic Account Management" of our handbook.  I'd like to put them
into the source file (basics/chapter.xml).

 Could anyone review that?

P.S.: my (xml-style) comments are denoted with 'XXX skipme:'.



Index: en_US.ISO8859-1/books/handbook/basics/chapter.xml
===
--- en_US.ISO8859-1/books/handbook/basics/chapter.xml   (revision 43325)
+++ en_US.ISO8859-1/books/handbook/basics/chapter.xml   (working copy)

...

@@ -637,7 +639,7 @@

   &os; provides a variety of different commands to manage
user accounts.  The most common commands are summarized in
-   Table 4.1, followed by some examples of their usage.  Refer to
+   the subsequent table, followed by some examples of their usage.  Refer 
to
the manual page for each utility for more details and usage
examples.

WB: "See" is simpler than "refer to".  An xml:id can be added to that 
table and linked here.  That is also useful when referring to the page 
in HTML, because it becomes an anchor.  For example, in the table 
declaration:


  

Then in the text:

   &os; provides a variety of different commands to manage
user accounts.  The most common commands are summarized in
, followed by some examples of 
their usage.  See
the manual page for each utility for more details and usage
examples.


@@ -725,8 +727,10 @@
  been invited into the
  wheel group,
  which is required to provide the account with superuser
- access.  When finished, the utility will prompt to either
+ access using &man.su.1;.  When finished, the utility will prompt to 
either

WB: That sentence can be interpreted several ways.  How about

  wheel group,
  allowing them to become the superuser
  with &man.su.1;.

  create another user or to exit.
+

WB: A mention of sudo would have to be careful not to equate it with 'su 
-'.  The environment is different.  I think the intention here was just 
to demonstrate adduser.  The section just above, called "The Superuser 
Account", would be a better place for describing sudo and how it can 
allow unprivileged users to run programs without becoming superuser.

___
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"