from:"gabor"


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).


Gabor
___
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


Em 01-06-2013 19:46, Chris Rees escreveu:

I don't see how anyone could disagree with that:)

Is there an "old version" capability there?

What do you exactly mean old version capability?

What I'm suggesting consists in that elements marked as edition="online" 
only go to the online version and those marked as edition="print" only 
go to the print version. The rest is rendered in both. This also 
requires setting some parameters in the Makefile and will just work.


Gabor
___
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


Em 01-06-2013 20:23, Chris Rees escreveu:
I'm thinking edition="FreeBSD-7" etc.  Just a thought, and it's 
probably irrelevant, sorry.

Not entirely possible yet but there are plans to support this.

Gabor
___
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


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.


Gabor
___
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

2013-06-02 Thread Gabor Kovesdan


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.


Gabor
___
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: print edition (was Re: removing 'changes' section from the online edition)

2013-06-02 Thread Gabor Kovesdan


Em 02-06-2013 17:03, Warren Block escreveu:
That means "include elements marked with edition="print" and all 
unprofiled elements"?

Yes. In other words: exclude elements, whose edition is not print.


For a print version, it might be easier to just go the opposite way: 
leave everything unprofiled as defaulting to print, and marking 
online-only sections as "online".
In the print branch it is possible to just mark online parts but if we 
want to work with single source we need both ways since there are some 
parts that are print-only. But I guess that the most of the Handbook may 
be unprofiled. Maybe we are late for going to a totally single source 
solution now but imho, we should do it the next time.


You have to watch out that the DocBook sources are valid both with 
and without the profiled element. For example, you cannot have two 
titles for the section with different edition values since only one 
title is allowed. In this case, you have to use the phrase element in 
the title.


That will probably be necessary for some things, like a print chapter 
that links to online-only chapters. 
If the reference is a sentence in a paragraph, you should use phrase. If 
it is a whole paragraph, you can add the markup para.


Gabor
___
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

2013-06-05 Thread Gabor Kovesdan


Em 05-06-2013 14:10, Hiroki Sato escreveu:

Gabor Kovesdan  wrote
   in <519fa4fe.4030...@freebsd.org>:

ga> username --> systemitem class="username"
ga> groupname --> systemitem class="groupname"
ga> hostid role="fqdn" --> systemitem class="fqdomainname"
ga> hostid role="hostname" --> systemitem class="fqdomainname"
ga> hostid role="domainname" --> systemitem class="fqdomainname"
ga> hostid role="netmask" --> systemitem class="netmask"
ga> hostid role="mac" --> systemitem class="etheraddress"
ga> hostid role="ipaddr" --> systemitem class="ipaddress"
ga> hostid --> systemitem

  Hmm, I do not like to create "a rule" to mark up both a username and
  a hostname by using  element without attribute.  Even if
  the rendering results are the same, they are different.  Is it
  problem with allowing both writing s without attribute
  and adding attributes into them later (or at the same time)?  I do
  not think limiting the vocabulary is useful for learning.  Allowing
  people who are not familiar with DocBook to mark up by using
   only should be enough if it is really an issue.
Technically it is easily possible to convert them "correctly", i.e. as 
described above, it was just my suggestion to leave out class 
attributes. It is also possible to allow systemitem with and without the 
class attribute specified.


ga> This is actually a type of file and the filename class attribute may
ga> also be devicefile, which expresses its semantics. Again, we should
ga> consider dropping the class attributes to simplify things:
ga> devicename --> filename class="devicefile"
ga>
ga> These are not actually distinguished in formatting and the package
ga> element expresses them better:
ga> filename role="package" --> package
ga> filename role="port" --> package

  package should support a role to distinguish if it is a port or a
  package because the linkend can be different.  The following DSSSL
  fragment was removed in our XSLT:


 (element filename
   (let* ((class (attribute-string (normalize "role"
 (cond
  ((equal? class "package")
   (let* ((urlurl"http://www.FreeBSD.org/cgi/url.cgi";)
  (href  (string-append urlurl "?ports/"
(data (current-node))
"/pkg-descr")))
 (create-link (list (list "HREF" href)) ($mono-seq$
  (else ($mono-seq$)

It's true that I didn't notice this distinction in the rendering. But 
why not addding this link to both packages and ports? My personal 
impression is that there are people, who mostly use packages and others, 
who use ports. This preference is independent from the context. If the 
text talks about the textproc/docproj ports but I prefer dealing with 
packages, I will still want to install the package and vice versa. In 
the essence, they are the same. This is why I would not distinguish them.


Gabor
___
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: print edition

2013-06-05 Thread Gabor Kovesdan


Em 05-06-2013 14:34, Hiroki Sato escreveu:

Gabor Kovesdan  wrote
   in<51ab6d32.1060...@freebsd.org>:

ga> Em 02-06-2013 17:03, Warren Block escreveu:
ga> > That means "include elements marked with edition="print" and all
ga> > unprofiled elements"?
ga> Yes. In other words: exclude elements, whose edition is not print.
ga> >
ga> > For a print version, it might be easier to just go the opposite way:
ga> > leave everything unprofiled as defaulting to print, and marking
ga> > online-only sections as "online".
ga> In the print branch it is possible to just mark online parts but if we
ga> want to work with single source we need both ways since there are some
ga> parts that are print-only. But I guess that the most of the Handbook
ga> may be unprofiled. Maybe we are late for going to a totally single
ga> source solution now but imho, we should do it the next time.

  I agree that preface and the pgpkey section can be different between
  the online and print version, but are there other parts like them?
Probably few. Maybe the formatting conventions since I suspect they may 
be different in the print edition.

  DocBook profiling will make the source complex, so we should try to
  minimize the differences between the online and print version, and
  separate the differences into different files wherever possible.  The
  profiling is like #ifdef in a C program.  It is useful for small
  parts, but using it too much just makes things complicated.
I believe the online/print markup will be limited and applied to 
upper-level elements like sect1 and won't normally escalated down to 
finer-grained markup. The separation in files is a good idea.


As for the version-specific markup, it would affect more parts but this 
is something that we have talked about for a long time. It wouldn't be 
just a support for the print edition but a desired feature.


Gabor
___
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: correct way to do links?

2013-06-19 Thread Gabor Kovesdan


Em 17-06-2013 21:24, Dru Lavigne escreveu:

1. Links to another section within the same document.

2. Links to another book or article within the FDP.

3. Links to an external website.

What is the correct usage for Docbook 4/5 for each type of link?

1. Links to another section within the same document:

Is this a  with the description to appear specified or an  with the 
section automatically rendered?

Yes.


2. Links to another book or article within the FDP:

Is this a  with the description to appear specified or an  with the 
section automatically rendered?
No. These work in a single documentation only. The best solution 
currently available is using  with a link to the XHTML version of 
the document at the FreeBSD website. The drawback of this is that it 
hardcodes the URL into the documents. A more XML-friendly solution would 
be olinking but it has never been configured and used in FreeBSD's 
DocBook sources. It could be a longer-term target to change to that but 
for now,  will do.


3. Should links to an external website use a  tag, an url=, and the 
description to appear? For example:

http://www.wi-fi.org/";>Wi-Fi alliance

Yes.

Gabor

___
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

2013-06-19 Thread Gabor Kovesdan


Em 17-06-2013 22:05, Dru Lavigne escreveu:

Can we have a summary for the FDP (and for the benefit of Handbook editors) of 
when/if systemitem class= should be used? Are there also systemitems for the 
different types of s which should be used instead?

The systemitem element is documented well here:
http://www.docbook.org/tdg5/en/html/systemitem.html

When to specify the class atttribute is our decision and as you see, 
there are different preferences. And it is important to note that at the 
moment we are using our extensions and  will only be used 
once we upgrade to DB 5.0. So the documentation should not be updated 
with this in head but in db5.


As for filename, it will be still  and we already use 
correctly the class names, yet it should be documented. The DocBook 
reference is here:

http://www.docbook.org/tdg5/en/html/filename.html

As for the FDP, it is another item, which we have to solve. I have some 
ideas in my mind but I haven't got there yet so I haven't started a 
discussion. First, I would like to more clearly separate it into 2-3 parts:
1, A technology introduction: XML, XHTML, DocBook, XSLT. A concise 
introduction to the ideas behind these technologies and how they can be 
used for technical documentation. I think it should be like a tutorial, 
which includes references but it's no use trying to create another XML, 
XHTML or DocBook reference. It should be limited to the minimal 
knowledge that is necessary to get started with our docs.
2, How we use these technologies in our documentation set, i.e. the 
FreeBSD-specific things. One with previous knowledge in DocBook would be 
able to start reading here. It could fit here whether we use classes on 
systemitems and how our .mk files work, etc.

3, The FreeBSD writing style. General advices, spelling, etc.

Gabor
___
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

2013-06-20 Thread Gabor Kovesdan


Em 20-06-2013 17:55, Hiroki Sato escreveu:

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.

  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.
I believe that XHTML is an online format by nature but pdf may also be 
distributed as an online snapshot after the actual release so I would 
also treat them separated as Warner suggests.


Gabor
___
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

2013-06-20 Thread Gabor Kovesdan


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.


Gabor
___
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

2013-07-03 Thread Gabor Kovesdan


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?


Gabor
___
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: [CFT] merging projects/entities

2013-07-06 Thread Gabor Kovesdan


Em 06-07-2013 12:52, René Ladan escreveu:

To test, you can either check out doc/projects/entities or doc/head and
apply the patch at [1]. After that, run 'make' in en_US.ISO8859-1/ or
'make WEB_ONLY=yes ENGLISH_ONLY=yes' in en_US.ISO8859-1/htdocs/ as usual.

[1]ftp://rene-ladan.nl/pub/freebsd/entities-r42173.diff
SHA256 = d6685fb654e9624f2e733fa7feb852515c2aed566150f588359fb89bbf72e2b3
SIZE = 423519
There are indentation-only changes in share/xml/catalog.xml. These parts 
shouldn't be changed or at least not with other changes if you want to 
improve them. Also, the real changes seem to be a bit messy, there are 
duplicated entries and some commented out ones and all of this 
intermixed with indentation changes so it is hard to see the overall 
effect. This file should be reviewed.


As for the email element, it doesn't logically belong to HTML so it 
shouldn't have the XHTML namespace. Actually, it is borrowed from 
DocBook, which doesn't have a namespace up to version 4.5. In turn, 
DocBook 5.0 has its own namespace. So I suggest to leave the email 
element in the empty namespace for now and with the DB 5.0 migration it 
will go to the DocBook namespace. For this, you also need to modify 
share/xml/xhtml.xsl and remove the namespace prefix in the match attribute:


+  
+<
+
+  
+   
+  
+  
+   
+ 
+   mailto:
+   
+ 
+ 
+   
+  
+
+>
+  

And with this change, this part becomes redundant:

--- share/xsl/freebsd-xhtml-common.xsl  
(svn+ssh://svn.freebsd.org/doc/projects/entities)   (working copy)
+++ svn+ssh://svn.freebsd.org/doc/projects/entities (revision 42173)
@@ -6,6 +6,7 @@
 version='1.0'
 xmlns="http://www.w3.org/TR/xhtml1/transitional";
xmlns:str="http://exslt.org/strings";
+   xmlns:xhtml="http://www.w3.org/1999/xhtml";
extension-element-prefixes="str"
 exclude-result-prefixes="#default">
 
@@ -162,6 +163,27 @@

 
   
 
+  

+
+  <
+  
+   
+ 
+   
+   
+ 
+   
+ mailto:
+ 
+   
+   
+ 
+   
+  
+  >
+
+  

The rest looks fine, thanks for your work on this!

Gabor
___
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: [CFT] merging projects/entities


Em 07-07-2013 17:19, René Ladan escreveu:

Do you mean that the email declarations in share/xml/authors.ent should
be removed again? For clarity I would prefer this, but this (and the
email XSLT templates) seem necessary to get
&a.committer.email; working in both the articles/books and webpages,
and for the latter it removes the need to write the cumbersome
"&a.committer; <mailto:commit...@freebsd.org";>commit...@freebsd.org>"
(in head, with &a.committer pulled in from the removed
share/xml/developers.ent) as
"&a.committer.email;" suffices.
No, I'm talking about the XML namespace. The xmlns=... part should be 
removed completely from email and this should also be reflected in the 
XHTML renderer XSLT, that is, email instead of xhtml:email. In turn, the 
template can be totally removed from the DocBook XSLT since DocBook 
handles properly the email element in the default (empty) namespace.


Gabor
___
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: [CFT] merging projects/entities


Em 07-07-2013 17:51, René Ladan escreveu:

Hm, if I understand correctly, these changes lose the role='nolink'
functionality in DocBook (i.e. there is now always a clickable link) and
for XHTML they results in build errors:

namespace warning : Namespace default prefix was not found
&a.tabthorpe; tabtho...@freebsd.org
  
Sorry, I missed the role attribute. The namespace should have been 
xmlns="". This patch seems to solve both problems and works fine:

http://kovesdan.org/patches/email-entities.diff

Gabor
___
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: [CFT] merging projects/entities


Em 07-07-2013 18:53, René Ladan escreveu:

Sorry, I missed the role attribute. The namespace should have been
>xmlns="". This patch seems to solve both problems and works fine:
>http://kovesdan.org/patches/email-entities.diff
>

Almost there, but using a nolink email address in htdocs fails with the
same error as above. Maybe share/xml/xhtml10-freebsd.dtd is the wrong
file to add this?

Just forgot to patch those with sed. Patch updated.

Gabor
___
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: [CFT] merging projects/entities


Em 07-07-2013 21:00, René Ladan escreveu:

Heh, missed that myself too. So now only tidying up or synchronizing
whitespace for share/xml/catalog.xml remains to be done?
Personally, I think it would be better to commit that whitespace fix 
separately. Even if you committed it separately in the branch, it would 
go to head intermixed with real changes, which makes it hard to read the 
backlog. This is a disadvantage in general and it is quite a big hassle 
for translators. I think you did it fine since you didn't have to 
foresee these consequences but maybe we should document it as a best 
practice to avoid whitespace changes in branches.


Gabor
___
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: [CFT] merging projects/entities

2013-07-08 Thread Gabor Kovesdan


Em 08-07-2013 00:24, René Ladan escreveu:

I didn't think it through this far, but you're right. I think it's best
to write this down somewhere in the FDP?
That sounds to be a good place for this. I believe this is not really 
important for the src tree so no need to put it into committers-guide.


For now this is fixed in head (r42191, whitespace-only forward commit)
and in
projects/entities (r42192, fix some inadvertent changes). The only
changes left are
those from r40196, which are intended (modulo inline whitespace:-(  ).
I think it's fine. At least you have reduced the differences and have 
made it easier to read the diffs. Next time we can count with this factor.


Gabor
___
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


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?


Gabor
___
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


Em 10-07-2013 00:10, Eitan Adler escreveu:

top posting, really?



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

>>One more thing to discuss: shall we maintain the sect1, sect2, ... elements
>>or just use section?

How would this be rendered in HTML?  Does this change anything?

As already mentioned: no. Not reading history, really? ;)

Gabor
___
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


Em 09-07-2013 20:49, Warren Block escreveu:
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? 

No, it's true, we can also change that later.

Gabor
___
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


Em 10-07-2013 13:19, Warren Block escreveu:

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 ] 

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

Gabor
___
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

2013-07-14 Thread Gabor Kovesdan


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.


- 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.


- 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.


- 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.


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.
Not in theory but theory doesn't always match practice. I'm working on 
the DocBook 5 change to provide better rendering and support publishing 
print versions. I'm evaluating and customizing two different rendering 
methods and I have to see where we can get with each. Practically I can 
do it by eliminating the confusing and bothering factors. This is 
sometimes done by customizing the rendering and sometimes by feeding 
back the results to the concrete documents.


Gabor
___
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

2013-07-14 Thread Gabor Kovesdan


On 2013.07.14. 18:02, Warren Block wrote:

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.
It is not appearance, it is structure, which is part of semantics. From 
a semantic point of view, what's an admonition? Imo, it is a piece of 
additional information that (1) is related to the wider context, (2) is 
more or less self-contained and (3) does not fit into the main text flow 
so its position is more or less flexible. It is usually rendereded with 
a border or a background color that clearly separates it from the main 
flow of the text. Because of these characteristics, it semantically 
doesn't fit into the notion of lists. Nor tables should be embedded into 
lists.


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.

It may help but that break of information flow still shouldn't be there.


- 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.
You are calling appearance what is in fact structure. We could talk 
about appearance if we wrote  or something like that.


The semantics of a title could be defined like a plain text title and 
that would be a valid semantics, too. True, it is also possible to solve 
it when rendering but if we decide that we don't want such in titles, 
why not just changing the semantics and sparing some stylesheet code? 
Both the docs and the stylesheets would be more simple.


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.


- 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,

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

2013-07-15 Thread Gabor Kovesdan


On 2013.07.14. 20:57, Warren Block wrote:

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. 
Ok, thank you for investigating this. If it is accepted then I don't 
object that much. But please let's keep these at a reasonable extent, 
e.g. monspace or italic but no colors.


Gabor
___
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

2013-07-15 Thread Gabor Kovesdan

On 2013.07.15. 6:58, Hiroki Sato wrote:

ga> The semantics of a title could be defined like a plain text title and
ga> that would be a valid semantics, too. True, it is also possible to
ga> solve it when rendering but if we decide that we don't want such in
ga> titles, why not just changing the semantics and sparing some
ga> stylesheet code? Both the docs and the stylesheets would be more
ga> simple.

I like to solve this upon rendering and I think it will be simpler
because a policy of plain text title (in markup) practically does not
work without DTD change, and elements such as can be
included in title elements via entity references or so in any way.
Forcing a consistent style for title elements looks easy to me.
I thought of adding some Schematron constraints for the problematic
cases but I'll go for the rendering customization if this is better
accepted. I agree that this may work better for entity references.

ga> > The previous toolchain rendered that title in bold:
ga>
>http://docs.freebsd.org/doc/9.0-RELEASE/usr/share/doc/freebsd/en_US.ISO8859-1/books/handbook/bsdinstall-pre.html
ga> > Agreed, that title does not look very good. Adding a colon to list
ga> > titles when rendering would help. Removing all list titles be too
ga> > severe.
ga> Having a colon at the end of the paragraph and another one at the end
ga> of the list title? It seems even more confusing to me.
ga> Why is to severe removing them? Do they add any extra information that
ga> helps you understanding the content? I think it makes the
ga> comprehension more difficult and is just counter-productive.
ga>
ga> Can you find a published book with such list titles?

I think removing title is fine. Although there are some exmaples for
such an informal title like this:

Pros:
- A
- B

Cons:
- C
- D

they are items, not "title" actually. If we really need it, it
should be a caption.
I believe these are already rendered as normal paragraphs between two
itemizedlists but I'll verify this.

Gabor
___
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"

CFR: documentation rendered in PDF with FOP


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.


Gabor
___
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


On 2013.07.23. 15:46, Daniel Seuffert wrote:

Fonts: Please have a close look at Gentium please, that's used on
our flyers for a lot of reasons:

http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=gentium
Thanks Daniel, it indeed seems nice! I've partly regenerated the 
documents, I'm still experimenting with font settings but now we are one 
step closer to the goal.


Gabor
___
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


On 2013.07.23. 23:11, Warren Block wrote:


Thanks for your work on this!

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

- Customization is more complicated.
- Overall outlook just doesn't look so nice. That may be improved by 
customization but that's not so trivial.
- It doesn't support programlistings in lists and several documents 
still fail because of this.
- Somehow it doesn't properly wrap non-Latin text: 
http://kovesdan.org/files/tex-ja.pdf
  Maybe it is trivial to fix, I just don't know how CJK text is handled 
in TeX. But I don't understand why something so trivial doesn't just 
work out of the box.


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.


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! 
Yes, I've also noticed that that page is quite weird. The line-wrap part 
should be easy to fix, we just have to add the comma as a possible 
wrapping character. It is stranger why the text overflows instead of 
causing a page break. The good thing is that the output of the renderer 
is very clean and we can clearly see which pages have overflows.


Gabor
___
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


On 2013.07.23. 23:55, Michael Ross wrote:
I just skimmed through the pdf of the german version of the 
developer's handbook and noticed some problems with syllabification at 
the end of lines.


Examples:
filename "fromboz.c" printed as
from-
boz.c
Do you think filenames and such should not be hyphenated at all? I've 
been thinking of it but that may sometimes result in weird spacing 
because of the justification.


"/usr/share/mk" printed as
/
share/mk

"Option -o" printed as
Option -
o

From the english version:
"" printed as


Plus, in some paragraphs nearly all lines end with a hyphen; I think 
that makes the whole hard to read.


If possible, I would turn syllabification off altogether. 
Hyphenation can still be improved and actually it is a requirement for 
printed publications. With hyphenation, justification works better and 
text should have a more pleasant outlook. We can tweak the dictionaries 
to avoid hyphenating the word FreeBSD and such. And as a last resort, we 
can still easily turn it off if we are not satisfied with the result. 
The rendering is still a work in progress. I'll see what I can do here.


Gabor
___
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

2013-07-24 Thread Gabor Kovesdan


On 2013.07.24. 1:28, Warren Block wrote:

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. 
Thanks! Some more guidelines on indexing would be useful. I'm unsure 
about the actual conventions, probably we should consult some 
bibliography. I'm thinking of some hints on what to index. We currently 
index company names. Should we do it or just technical terms? Shall we 
index acronyms or the full term and add a see entry for the former ones? 
How should we use secondary terms? As for translations, I think that 
indexterms should be translated if the term is translated in the body 
text but currently it is not always done. We should clarify these questions.


Gabor
___
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: and other tag usage

2013-07-25 Thread Gabor Kovesdan


On 2013.07.25. 20:15, Warren Block wrote:
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? 
I prefer the first approach. The emphasis is on what the user should 
type and not on the fact that it is a filename. Besides, the green 
rendering inside the userinput would be too much.


Gabor
___
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


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.


Gabor
___
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


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

Gabor
___
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


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.


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.


Gabor
___
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


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.


Gabor
___
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


On 2013.07.28. 22:23, Glen Barber wrote:

On Sun, Jul 28, 2013 at 10:17:50PM +0200, Gabor Kovesdan wrote:

>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.
>

Yes, please, let's keep it Java-free...

IMHO, it is bad enough some of use require use of Java for basic web
browsing.  Adding that to a our doc build is a big red bug.

What do you mean for basic web browsing? Where is Java required for that?

Gabor
___
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


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.

Gabor
___
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