 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 14-6-2014 19:39, Orchid Win7 v1 wrote:
> On 14/06/2014 04:51 PM, andrel wrote:
>> For the source control part...
>> Both .docx and .odt are in fact zip containers that contain the images
>> and the content in different files. In theory you could extract the
>> content part, put that under revision control.
>
> Yeah, but that probably won't work well in practice.
>
> For example, we use a system called SpecFlow where you write integration
> tests in psuedo-English, and an external DLL transforms that into C#
> code. Both the source and the generated C# code are in source control.
> But the trouble is, if you insert or remove a single line in the
> SpecFlow file, the *entire* C# file changes. (Every line of the
> generated file is annotated with the corresponding line number in the
> SpecFlow file.)
>
> I rather suspect that when you save an ODF file, the editor rebuilds the
> entire file and it won't look anything like what it did before. (I
> haven't tried, but I suspect that's what'll happen.) The other problem,
> of course, is that it's hard to make really polished ODF files in the
> first place. ;-)
it is clear that you haven't checked ;)
I made a little document saved it as .odt and opened it as .zip.
In it is the content.xml file that after a lot of presumable
initialization contains (I added some newlines):
--------contents.xml---------------
.
.
.
<text:h text:style-name="Heading_20_1" text:outline-level="1">This is a
file for andy</text:h><text:p text:style-name="Text_20_body"/>
<text:p text:style-name="Text_20_body">Add a mascot below</text:p>
<text:p text:style-name="Text_20_body">
<draw:frame draw:style-name="fr1" draw:name="graphics1"
text:anchor-type="as-char" svg:width="5.292cm" svg:height="8.255cm"
draw:z-index="0">
<draw:image
xlink:href="http://upload.wikimedia.org/wikipedia/commons/thumb/5/5b/RoyalRegimentWalesGoat_gobeirne.jpg/200px-RoyalRegimentWalesGoat_gobeirne.jpg"
xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad"/>
</draw:frame>
</text:p>
<text:p text:style-name="Text_20_body">see, it is above </text:p>
.
.
.
-----------end contents.xml------------
Easy enough to understand, to modify and to repackage. The image was
added as a link. If you add it to the document it will be in a directory
local to the zip file.
--
Everytime the IT department forbids something that a researcher deems
necessary for her work there will be another hole in the firewall.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> But a tool alone isn't (hopefully obviously) going to give you great
> documentation. You also need technical writers (at least one).
I'd like to take a stab at this myself. I believe I'm quite a good
writer. The question, of course, is whether I can find the time to do this.
Trouble is, currently the documentation sucks, but nobody has the time
to produce something better, so we're just doing minor tweaks to it
whenever the product changes. Really the entire thing wants to be thrown
in the bin and somebody to start again. But if I turn up and go "hey,
here's the new manual" and it's *not* as shiny and pretty to look at as
the old one... nobody tell take any notice.
> The nice thing about using an XML standard like DITA is that you can use
> xslt to transform it, so if you need to customise the transformation,
> it's trivial to do - if you know xslt.
DocBook is an XML standard. So - in theory - it's "trivial" to make it
do what you want.
...in reality, I found it hellishly difficult to change even the tiniest
detail about it. Perhaps it would be simpler to rewrite the XSLT from
scratch rather than try to figure out how it works. And maybe, just
maybe, the XML-FO processor I'm using just can't be convinced to produce
nice output.
For that matter, we could write documentation in HTML and apply lashings
of CSS to it. You can do paper-specific CSS settings and so forth, and
everybody in the room already knows how CSS and HTML work. Again, the
trouble is, you'll never get it to look slick and polished.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
> The other problem,
> of course, is that it's hard to make really polished ODF files in the
> first place. ;-)
>
No it's not. It only requires a bit of planning, and military
enforcement of the rules, if you have multiple editors.
>> Alternatively, many programs nowadays support
>> version control. Did you check if InDesign does?
>
> As I say, nobody here seems to know how to work InDesign. It wouldn't
> surprise me if our current workflow can be significantly improved just
> by changing how the document it set up...
Yes.
I don't know InDesign, but I knew a few of its ancestors.
Just as CSS with HTML, or a complex software program, you need a plan
and _you need to stick to it_.
- Define styles (ex: title, subtitles, section heading, text, code,
examples,etc...) *AND USE TO THEM* No more "I know the subtitle is
Arial 14 pts, bold, so I'll manually change the properties of that
sentence."
- Create page templates (left side should look like this, right side
should look like that, first page of a chapter should look like that,
etc...)
- Put section titles macros in the headers, and page number macros in
the footers.
- Generate the table of contents automatically.
- Put someone in charge of maintaining the manual. He or she can (and
should) accept input from the rest of the team, but he or she has the
last word on the format.
- That someone should have a backup, in case of vacations or wild bus
rampage.
Tada!
Whether you use WordPerfect 5.1, vi and LaTex, emacs, Office365, or the
latest Adobe Creative Suite, the above rules will have your manual at
least look decent.
--
/*Francois Labreque*/#local a=x+y;#local b=x+a;#local c=a+b;#macro P(F//
/* flabreque */L)polygon{5,F,F+z,L+z,L,F pigment{rgb 9}}#end union
/* @ */{P(0,a)P(a,b)P(b,c)P(2*a,2*b)P(2*b,b+c)P(b+c,<2,3>)
/* gmail.com */}camera{orthographic location<6,1.25,-6>look_at a }
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-14 17:38, Orchid Win7 v1 a écrit :
>> But a tool alone isn't (hopefully obviously) going to give you great
>> documentation. You also need technical writers (at least one).
>
> I'd like to take a stab at this myself. I believe I'm quite a good
> writer. The question, of course, is whether I can find the time to do this.
>
> Trouble is, currently the documentation sucks, but nobody has the time
> to produce something better, so we're just doing minor tweaks to it
> whenever the product changes. Really the entire thing wants to be thrown
> in the bin and somebody to start again. But if I turn up and go "hey,
> here's the new manual" and it's *not* as shiny and pretty to look at as
> the old one... nobody tell take any notice.
>
>> The nice thing about using an XML standard like DITA is that you can use
>> xslt to transform it, so if you need to customise the transformation,
>> it's trivial to do - if you know xslt.
>
> DocBook is an XML standard. So - in theory - it's "trivial" to make it
> do what you want.
>
> ...in reality, I found it hellishly difficult to change even the tiniest
> detail about it. Perhaps it would be simpler to rewrite the XSLT from
> scratch rather than try to figure out how it works.
Right, because RTFMing is impossible...
> And maybe, just
> maybe, the XML-FO processor I'm using just can't be convinced to produce
> nice output.
>
Your problem, is that you do not like the default CSS used by your
docbook editor, not that it can't be convinced to produce nice output.
The problem is not with the tool. The problem is with what you're
telling your tool to do (or not telling it to do). As I said in my
other response, any word processor younger than you is able to print
crisp Arial 16pts or justify text properly.
If you want your manual to look good, you actually have to tell whatever
tool you plan on using that you want it to look good.
You need to create page templates that look good.
You need to chose font combinations that are pleasing to the eye:
sans-serif for titles, serif for text body, monospace for code or
command line text.
UNDER NO CIRCUMSTANCE SHOULD YOU USE COMIC SANS.
You need to chose colors wisely.
Etc...
Of course, some software packages will make this easier to do than
others, but regardless of your choice of software, noe of what you are
trying to do is impossible, even for someone who doesn't have the artist
gene, like you.
Your current manual looks impressive? You like its look? Then recreate
the same thing with something you're familiar with, if you can't wrap
your head around InDesign, or DocBook.
But the more important thing is - as you mention - the quality of the
content. Start by writing good content in Notepad (or vi, or gedit, or
whatever) so that you can focus on the content.
Then import that text into some document formatting tool and apply the
styles you have chosen to it.
--
/*Francois Labreque*/#local a=x+y;#local b=x+a;#local c=a+b;#macro P(F//
/* flabreque */L)polygon{5,F,F+z,L+z,L,F pigment{rgb 9}}#end union
/* @ */{P(0,a)P(a,b)P(b,c)P(2*a,2*b)P(2*b,b+c)P(b+c,<2,3>)
/* gmail.com */}camera{orthographic location<6,1.25,-6>look_at a }
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 16/06/14 14:26, Francois Labreque wrote:
>
> But the more important thing is - as you mention - the quality of the
> content. Start by writing good content in Notepad (or vi, or gedit, or
> whatever) so that you can focus on the content.
>
> Then import that text into some document formatting tool and apply the
> styles you have chosen to it.
Excellent advice, Francois. Now the only problem is getting Andrew (and
others in the same position) to follow it.
John
--
Protect the Earth
It was not given to you by your parents
You hold it in trust for your children
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> DocBook is an XML standard. So - in theory - it's "trivial" to make it
>> do what you want.
>>
>> ...in reality, I found it hellishly difficult to change even the tiniest
>> detail about it. Perhaps it would be simpler to rewrite the XSLT from
>> scratch rather than try to figure out how it works.
>
> Right, because RTFMing is impossible...
Most things to do with XML are hard. For whatever reason, XML is
absurdly overcomplicated, considering what it actually does.
It took me hours of Google searching just to figure out how to make
DocBook allow me to write character entities. (The manual says it works
already... Oh, wait, that's for DocBook v4. OK, so how do you make it
work for v5? Oh yeah, we removed that feature. Great, so how do I turn
it back on?) I got there eventually, but it was a hell of a lot of work.
Similar fun with XInclude. The manual tells you that XInclude is a great
way to make modular documents - and so much better than the old entity
workaround we used to recommend you use. Except, you know what? My XML
validator and my XSLT processor both POINT-BLANK INGORE any and all
XInclude declarations. Isn't that wonderful?
>> And maybe, just
>> maybe, the XML-FO processor I'm using just can't be convinced to produce
>> nice output.
>
> Your problem, is that you do not like the default CSS used by your
> docbook editor, not that it can't be convinced to produce nice output.
I don't have a "DocBook editor", I have a text editor with a vague
understanding of XML. And then I have various command-line tools which,
after about a day of research, I was able to convince to produce PDF
output. Fortunately, all of this knowledge can be embedded into scripts. ;-)
> The problem is not with the tool. The problem is with what you're
> telling your tool to do (or not telling it to do). As I said in my other
> response, any word processor younger than you is able to print crisp
> Arial 16pts or justify text properly.
Yes, but can it render the chapter titles in a blue box with rounded
corners and a fuzzy drop-shadow? Probably not.
> Your current manual looks impressive? You like its look? Then recreate
> the same thing with something you're familiar with, if you can't wrap
> your head around InDesign, or DocBook.
As I say, I can't actually put my finger on exactly what it is about the
current manual that makes it look so good. It probably isn't any one
particular thing, it's the cumulative total of many, many small things...
> But the more important thing is - as you mention - the quality of the
> content. Start by writing good content in Notepad (or vi, or gedit, or
> whatever) so that you can focus on the content.
>
> Then import that text into some document formatting tool and apply the
> styles you have chosen to it.
Whilst I agree wholeheartedly, if we write a whole bunch of content as
(say) TeX input and then decide that actually our tool of choice wants
XML (or vice versa)...
That's kind of why I'd like to pin down exactly what tool we're going to
use. Once we start the rewrite, I only want to do it once.
Still, I could sit down and look at the high-level document structure -
that's very easy to change for any tool.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-16 14:39, Orchid Win7 v1 a écrit :
>>> DocBook is an XML standard. So - in theory - it's "trivial" to make it
>>> do what you want.
>>>
>>> ...in reality, I found it hellishly difficult to change even the tiniest
>>> detail about it. Perhaps it would be simpler to rewrite the XSLT from
>>> scratch rather than try to figure out how it works.
>>
>> Right, because RTFMing is impossible...
>
> Most things to do with XML are hard. For whatever reason, XML is
> absurdly overcomplicated, considering what it actually does.
>
Convince your boss to buy you this:
http://shop.oreilly.com/product/9780596805012.do
But what's so complicated about:
<chapter>
<title>Lorem ipsum</title>
<para>dolor sit amet</para>
</Chapter>
There's also wiki.docbook.org, but it seems to be running on an ailing
386... I gave up waiting for it, just to rebuke someone on a newsgroup.
> It took me hours of Google searching just to figure out how to make
> DocBook allow me to write character entities. (The manual says it works
> already... Oh, wait, that's for DocBook v4. OK, so how do you make it
> work for v5? Oh yeah, we removed that feature. Great, so how do I turn
> it back on?) I got there eventually, but it was a hell of a lot of work.
http://www.docbook.org/docs/howto/#entities
http://www.docbook.org/docs/howto/#faq-authoring-general-entities
>
> Similar fun with XInclude. The manual tells you that XInclude is a great
> way to make modular documents - and so much better than the old entity
> workaround we used to recommend you use. Except, you know what? My XML
> validator and my XSLT processor both POINT-BLANK INGORE any and all
> XInclude declarations. Isn't that wonderful?
>
Upgrade?
>>> And maybe, just
>>> maybe, the XML-FO processor I'm using just can't be convinced to produce
>>> nice output.
>>
>> Your problem, is that you do not like the default CSS used by your
>> docbook editor, not that it can't be convinced to produce nice output.
>
> I don't have a "DocBook editor", I have a text editor with a vague
> understanding of XML. And then I have various command-line tools which,
> after about a day of research, I was able to convince to produce PDF
> output. Fortunately, all of this knowledge can be embedded into scripts.
> ;-)
http://www.docbook.org/docs/howto/#editors
>
>> The problem is not with the tool. The problem is with what you're
>> telling your tool to do (or not telling it to do). As I said in my other
>> response, any word processor younger than you is able to print crisp
>> Arial 16pts or justify text properly.
>
> Yes, but can it render the chapter titles in a blue box with rounded
> corners and a fuzzy drop-shadow? Probably not.
>
The fuzzy drop shadow and rounded corners are not part of the CSS
specification (yet!), so it would require tinkering (ex: running the XML
through a preprocessor to convert every TITLE block into a table that
has specific images as a background), but it's not impossible.
For the rest:
//Andy.css
CHAPTER TITLE {
background-color: blue;
color: white;
font-family: Arial Verdana Sand-serif;
font-variant: small-caps;
font-weight: bold;
font-size: 24pt;
}
and then use that stylesheet when processing your .xml file.
>> Your current manual looks impressive? You like its look? Then recreate
>> the same thing with something you're familiar with, if you can't wrap
>> your head around InDesign, or DocBook.
>
> As I say, I can't actually put my finger on exactly what it is about the
> current manual that makes it look so good. It probably isn't any one
> particular thing, it's the cumulative total of many, many small things...
>
>> But the more important thing is - as you mention - the quality of the
>> content. Start by writing good content in Notepad (or vi, or gedit, or
>> whatever) so that you can focus on the content.
>>
>> Then import that text into some document formatting tool and apply the
>> styles you have chosen to it.
>
> Whilst I agree wholeheartedly, if we write a whole bunch of content as
> (say) TeX input and then decide that actually our tool of choice wants
> XML (or vice versa)...
Which is why you shouldn't write it with ANY output format or tool in
mind. Think a big README.TXT
>
> That's kind of why I'd like to pin down exactly what tool we're going to
> use. Once we start the rewrite, I only want to do it once.
While it's not a bad idea to have an idea of where you're going, it
shouldn't be your main consideration yet. You should focus on making
the documentation up to date, first.
>
> Still, I could sit down and look at the high-level document structure -
> that's very easy to change for any tool.
Yep.
--
/*Francois Labreque*/#local a=x+y;#local b=x+a;#local c=a+b;#macro P(F//
/* flabreque */L)polygon{5,F,F+z,L+z,L,F pigment{rgb 9}}#end union
/* @ */{P(0,a)P(a,b)P(b,c)P(2*a,2*b)P(2*b,b+c)P(b+c,<2,3>)
/* gmail.com */}camera{orthographic location<6,1.25,-6>look_at a }
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>>>> DocBook is an XML standard. So - in theory - it's "trivial" to make it
>>>> do what you want.
>>>>
>>>> ...in reality, I found it hellishly difficult to change even the
>>>> tiniest
>>>> detail about it. Perhaps it would be simpler to rewrite the XSLT from
>>>> scratch rather than try to figure out how it works.
>>>
>>> Right, because RTFMing is impossible...
>>
>> Most things to do with XML are hard. For whatever reason, XML is
>> absurdly overcomplicated, considering what it actually does.
>>
>
> Convince your boss to buy you this:
> http://shop.oreilly.com/product/9780596805012.do
I sorely doubt that any of that book will say anything whatsoever about
the toolchain problems I'm struggling with. It'll just be 500 pages
about the actual DocBook markup itself - which I'm having no problem with.
> But what's so complicated about:
>
> <chapter>
> <title>Lorem ipsum</title>
> <para>dolor sit amet</para>
> </Chapter>
OK, now go re-read what I actually said.
Writing the DocBook stuff itself is easy enough. (That's why I'm looking
at it in the first place.) Configuring the DocBook XSLT stuff is
difficult. Trying to make entities work is difficult. Trying to split
the file into parts is difficult. All the stuff that isn't to do with
writing the actual textual content just seems really difficult.
>> It took me hours of Google searching just to figure out how to make
>> DocBook allow me to write character entities. (The manual says it works
>> already... Oh, wait, that's for DocBook v4. OK, so how do you make it
>> work for v5? Oh yeah, we removed that feature. Great, so how do I turn
>> it back on?) I got there eventually, but it was a hell of a lot of work.
>
> http://www.docbook.org/docs/howto/#entities
This is about how to make XSLT not strip off custom entities that you
personally have defined (e.g., your product's name). It has nothing to
do with standard entities like .
> http://www.docbook.org/docs/howto/#faq-authoring-general-entities
This is the *actual* solution. Do you have *any idea* how many Google
searches it took me to find this exact page?? (Also, why does every
single webpage related to DocBook take five lifetimes to load?)
>> Similar fun with XInclude. The manual tells you that XInclude is a great
>> way to make modular documents - and so much better than the old entity
>> workaround we used to recommend you use. Except, you know what? My XML
>> validator and my XSLT processor both POINT-BLANK INGORE any and all
>> XInclude declarations. Isn't that wonderful?
>
> Upgrade?
To what? I'm using the latest versions of the tools recommended from the
DocBook website! :-P
>>> Your problem, is that you do not like the default CSS used by your
>>> docbook editor, not that it can't be convinced to produce nice output.
>>
>> I don't have a "DocBook editor", I have a text editor with a vague
>> understanding of XML. And then I have various command-line tools which,
>> after about a day of research, I was able to convince to produce PDF
>> output. Fortunately, all of this knowledge can be embedded into scripts.
>> ;-)
>
> http://www.docbook.org/docs/howto/#editors
OK, so... Emacs, oXygen (which is just a general XML editor) and a
couple of other XML editors. Doesn't really offer any meaningful
advantage over any other text editor. And really, this isn't the part
that's causing trouble in the first place.
>> Yes, but can it render the chapter titles in a blue box with rounded
>> corners and a fuzzy drop-shadow? Probably not.
>
> The fuzzy drop shadow and rounded corners are not part of the CSS
> specification (yet!)
Indeed. That's my point. A tool focused on flashy graphics will have all
these sorts of capabilities - possibly at the expense of making it
harder to update the content though. (I say *possibly* - I still haven't
got to the bottom of what InDesign's actual capabilities may or may not be.)
>> Whilst I agree wholeheartedly, if we write a whole bunch of content as
>> (say) TeX input and then decide that actually our tool of choice wants
>> XML (or vice versa)...
>
> Which is why you shouldn't write it with ANY output format or tool in
> mind. Think a big README.TXT
Sure. But the final thing is going to need markup. And I don't really
want to take a huge document and completely redo it to insert that
markup. It's much easier to insert markup as you write the thing in the
first place...
>> Still, I could sit down and look at the high-level document structure -
>> that's very easy to change for any tool.
>
> Yep.
Well then that's something productive I can actually go work on.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On Sat, 14 Jun 2014 22:38:40 +0100, Orchid Win7 v1 wrote:
>> But a tool alone isn't (hopefully obviously) going to give you great
>> documentation. You also need technical writers (at least one).
>
> I'd like to take a stab at this myself. I believe I'm quite a good
> writer.
From what I've seen, that belief has a good foundation.
> The question, of course, is whether I can find the time to do
> this.
That is always a challenge when it's not part of the official duties.
> Trouble is, currently the documentation sucks, but nobody has the time
> to produce something better, so we're just doing minor tweaks to it
> whenever the product changes. Really the entire thing wants to be thrown
> in the bin and somebody to start again. But if I turn up and go "hey,
> here's the new manual" and it's *not* as shiny and pretty to look at as
> the old one... nobody tell take any notice.
You might do a little research on "targeted documentation." The idea
behind this is to break documentation into procedures, concepts, and
reference material - something that DITA is actually designed around.
>> The nice thing about using an XML standard like DITA is that you can
>> use xslt to transform it, so if you need to customise the
>> transformation, it's trivial to do - if you know xslt.
>
> DocBook is an XML standard. So - in theory - it's "trivial" to make it
> do what you want.
True.
> ...in reality, I found it hellishly difficult to change even the tiniest
> detail about it. Perhaps it would be simpler to rewrite the XSLT from
> scratch rather than try to figure out how it works. And maybe, just
> maybe, the XML-FO processor I'm using just can't be convinced to produce
> nice output.
It's "trivial" once you understand it, just like using InDesign,
FrameMaker, or Blender, though, it's got a learning curve, and it's not
something you're going to understand overnight.
> For that matter, we could write documentation in HTML and apply lashings
> of CSS to it. You can do paper-specific CSS settings and so forth, and
> everybody in the room already knows how CSS and HTML work. Again, the
> trouble is, you'll never get it to look slick and polished.
One of the nice things about working with DITA is that you can easily
transform it (with the right tools) to XHTML or HTML. You can also get a
really slick publication out of it, because it can easily be transformed
to a PDF or other e-Book format (I'm partial to EPUB myself, and if
you're generating HTML, EPUB isn't much of a stretch).
Jim
--
"I learned long ago, never to wrestle with a pig. You get dirty, and
besides, the pig likes it." - George Bernard Shaw
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-16 17:25, Orchid Win7 v1 a écrit :
>>>>> DocBook is an XML standard. So - in theory - it's "trivial" to make it
>>>>> do what you want.
>>>>>
>>>>> ...in reality, I found it hellishly difficult to change even the
>>>>> tiniest
>>>>> detail about it. Perhaps it would be simpler to rewrite the XSLT from
>>>>> scratch rather than try to figure out how it works.
>>>>
>>>> Right, because RTFMing is impossible...
>>>
>>> Most things to do with XML are hard. For whatever reason, XML is
>>> absurdly overcomplicated, considering what it actually does.
>>>
>>
>> Convince your boss to buy you this:
>> http://shop.oreilly.com/product/9780596805012.do
>
> I sorely doubt that any of that book will say anything whatsoever about
> the toolchain problems I'm struggling with. It'll just be 500 pages
> about the actual DocBook markup itself - which I'm having no problem with.
>
Sorry. Linked the wrong book. This is the one you need.
http://www.sagehill.net/book-description.html
By the way, both books are available online for free:
http://www.docbook.org/tdg5/en/html/docbook.html
http://www.sagehill.net/docbookxsl/index.html
>> But what's so complicated about:
>>
>> <chapter>
>> <title>Lorem ipsum</title>
>> <para>dolor sit amet</para>
>> </Chapter>
>
> OK, now go re-read what I actually said.
>
> Writing the DocBook stuff itself is easy enough. (That's why I'm looking
> at it in the first place.) Configuring the DocBook XSLT stuff is
> difficult. Trying to make entities work is difficult. Trying to split
> the file into parts is difficult. All the stuff that isn't to do with
> writing the actual textual content just seems really difficult.
>
>>> It took me hours of Google searching just to figure out how to make
>>> DocBook allow me to write character entities. (The manual says it works
>>> already... Oh, wait, that's for DocBook v4. OK, so how do you make it
>>> work for v5? Oh yeah, we removed that feature. Great, so how do I turn
>>> it back on?) I got there eventually, but it was a hell of a lot of work.
>>
>> http://www.docbook.org/docs/howto/#entities
>
> This is about how to make XSLT not strip off custom entities that you
> personally have defined (e.g., your product's name). It has nothing to
> do with standard entities like .
>
Ok. i thought it had to do with not losing entities in a v4 doc when
upgrading to v5. I thought you were upgrading v4 documents to v5, not
using a v4 book to write v5 docs. Sorry.
>> http://www.docbook.org/docs/howto/#faq-authoring-general-entities
>
> This is the *actual* solution. Do you have *any idea* how many Google
> searches it took me to find this exact page?? (Also, why does every
> single webpage related to DocBook take five lifetimes to load?)
>
It took me one attempt.
google "docbook".
docbook.org seems promising...
Oh! they have a Documentation section...
Ah! There's a "Users migrating from v4 to v5 should read..." link.
Hey! They even mention entities...
Sometimes Google just shows you how to fish. It doesn't always serve
you grilled salmon with a mango chutney.
>>> Similar fun with XInclude. The manual tells you that XInclude is a great
>>> way to make modular documents - and so much better than the old entity
>>> workaround we used to recommend you use. Except, you know what? My XML
>>> validator and my XSLT processor both POINT-BLANK INGORE any and all
>>> XInclude declarations. Isn't that wonderful?
>>
>> Upgrade?
>
> To what? I'm using the latest versions of the tools recommended from the
> DocBook website! :-P
>
So you're saying that the latest and greatest release of your tool has a
problem with this:
1 <book xmlns="http://docbook.org/ns/docbook"
2 xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
<title>My First Book</title>
4 <xi:include href="chap1.xml"/>
<xi:include href="chap2.xml"/>
6 <xi:include href="chap3.xml"/>
<xi:include href="appa.xml"/>
8 <xi:include href="appb.xml"/>
</book>
(actual example from chapter 2 of the aforementioned O'RLY book)
That XInclude page is dated 2 May 2005. I maintain my suggestion to
upgrade to something more recent...
>>>> Your problem, is that you do not like the default CSS used by your
>>>> docbook editor, not that it can't be convinced to produce nice output.
>>>
>>> I don't have a "DocBook editor", I have a text editor with a vague
>>> understanding of XML. And then I have various command-line tools which,
>>> after about a day of research, I was able to convince to produce PDF
>>> output. Fortunately, all of this knowledge can be embedded into scripts.
>>> ;-)
>>
>> http://www.docbook.org/docs/howto/#editors
>
> OK, so... Emacs, oXygen (which is just a general XML editor) and a
> couple of other XML editors. Doesn't really offer any meaningful
> advantage over any other text editor. And really, this isn't the part
> that's causing trouble in the first place.
>
They have embedded XML validators, syntax highlighting, online help, etc...
>>> Yes, but can it render the chapter titles in a blue box with rounded
>>> corners and a fuzzy drop-shadow? Probably not.
>>
>> The fuzzy drop shadow and rounded corners are not part of the CSS
>> specification (yet!)
>
> Indeed. That's my point. A tool focused on flashy graphics will have all
> these sorts of capabilities - possibly at the expense of making it
> harder to update the content though. (I say *possibly* - I still haven't
> got to the bottom of what InDesign's actual capabilities may or may not
> be.)
>
You shouldn't have any problem updating the title of any chapter, while
having it retain its blue box with fuzzy drop shadows. you may,
however, have problems keeping section numbers in order, if you start
moving stuff around, as it looks as if people didn't know how to work
with the document (much like most people are horrible at working with
titles, subtitles, and bulleted lists in Word)
--
/*Francois Labreque*/#local a=x+y;#local b=x+a;#local c=a+b;#macro P(F//
/* flabreque */L)polygon{5,F,F+z,L+z,L,F pigment{rgb 9}}#end union
/* @ */{P(0,a)P(a,b)P(b,c)P(2*a,2*b)P(2*b,b+c)P(b+c,<2,3>)
/* gmail.com */}camera{orthographic location<6,1.25,-6>look_at a }
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
|
|
