 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
According to a friend of mine that has used InDesign for some personal
projects, InDesign can export and import XML. That could mean that you
only have to create a template and then insert the documentation by
automatic search and replace. (I use the same technique to build simple
websites.)
Apparently InDesign even has scripting facilities, she has not used them
herself. She is not a programmer, but a child of the WYSIWYG point and
click generation. All in all it sounds to me as something that matches
your interests and abilities. Perhaps she can even help you a bit. She
has met people that use complex programs to do simple tasks before (i.e.
we have worked together for some time).
--
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 18/06/2014 08:40 PM, andrel wrote:
> According to a friend of mine that has used InDesign for some personal
> projects, InDesign can export and import XML. That could mean that you
> only have to create a template and then insert the documentation by
> automatic search and replace. (I use the same technique to build simple
> websites.)
> Apparently InDesign even has scripting facilities, she has not used them
> herself. She is not a programmer, but a child of the WYSIWYG point and
> click generation. All in all it sounds to me as something that matches
> your interests and abilities. Perhaps she can even help you a bit. She
> has met people that use complex programs to do simple tasks before (i.e.
> we have worked together for some time).
OK. Well that all sounds like something worth looking into.
(I overheard the guy who's working on the documentation the other day.
We was explaining - as if this is a really complex and novel idea - how
he's managed to configure InDesign in such a way that it *automatically*
updates the table of contents and the index when you change something.
As if this is a really sophisticated idea, rather than - you know -
something that EVERY half-decent document production system should be
able to do out-of-the-box...)
It sounds like with some suitable tinkering, we could probably get quite
a nice workflow with this thing.
I wonder if there's any official documentation for it online. I'll take
a look...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>
> I wonder if there's any official documentation for it online. I'll take
> a look...
https://helpx.adobe.com/ca/indesign.html
(You'll need to replace the "ca" bit of the URL...)
- Go to adobe.com
- Click on menu
- Click on the inDesign icon
- Click Learn & support
--
/*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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Orchid Win7 v1 <voi### [at] dev null> wrote:
> On 18/06/2014 08:40 PM, andrel wrote:
> > According to a friend of mine that has used InDesign for some personal
> > projects, InDesign can export and import XML. That could mean that you
> > only have to create a template and then insert the documentation by
> > automatic search and replace. (I use the same technique to build simple
> > websites.)
> > Apparently InDesign even has scripting facilities, she has not used them
> > herself. She is not a programmer, but a child of the WYSIWYG point and
> > click generation. All in all it sounds to me as something that matches
> > your interests and abilities. Perhaps she can even help you a bit. She
> > has met people that use complex programs to do simple tasks before (i.e.
> > we have worked together for some time).
>
> OK. Well that all sounds like something worth looking into.
>
> (I overheard the guy who's working on the documentation the other day.
> We was explaining - as if this is a really complex and novel idea - how
> he's managed to configure InDesign in such a way that it *automatically*
> updates the table of contents and the index when you change something.
> As if this is a really sophisticated idea, rather than - you know -
> something that EVERY half-decent document production system should be
> able to do out-of-the-box...)
>
> It sounds like with some suitable tinkering, we could probably get quite
> a nice workflow with this thing.
>
> I wonder if there's any official documentation for it online. I'll take
> a look...
Good idea. I have had to work with indesign files given by clients and I managed
to work with it. I wouldn't compare the learning curve to Blender at all,
InDesign is a lot easier.
Alternatively afaik SVG supports feathered dropshadows and rounded boxes. I
think SVG could be the future of design because it seems to support just about
everything needed for print and web.
-Nekar Xenos-
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 19/06/2014 07:43, Nekar Xenos a écrit :
> Alternatively afaik SVG supports feathered dropshadows and rounded boxes. I
> think SVG could be the future of design because it seems to support just about
> everything needed for print and web.
svg has even draft about multipage... which, with the ability to use CSS
at top of svg file, might or might not be a good thing.
In formating of the page, there is already the World vs North-America
(A4 vs US letter). Either you designed your template to only use the
common area, dropping the margin (width 210 vs 216 mm, height 297 vs 279
mm, so 6 mm & 18 mm of white..), or you didn't and the change of paper
becomes "interesting" (truncated text, or repaginated with references
becoming wrong...)
A document is more than a collection of pages.
And remember: your documents will be migrated to the new company logo
and charts when the bigger corporation buy your company... or resell
it... or change its visual identity, or want to explore a new market.
Better keep a strict separation between formatting and content. (your
diagrams & pictures might show the company logo, but it should not be
copied inside every of them, it should be part of the formatting data
that can be referenced by them). The company name as well as the product
name are also not part of the content.
--
Just because nobody complains does not mean all parachutes are perfect.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Le 2014-06-19 02:27, Le_Forgeron a écrit :
> Le 19/06/2014 07:43, Nekar Xenos a écrit :
>
>> Alternatively afaik SVG supports feathered dropshadows and rounded boxes. I
>> think SVG could be the future of design because it seems to support just about
>> everything needed for print and web.
>
>
> svg has even draft about multipage... which, with the ability to use CSS
> at top of svg file, might or might not be a good thing.
>
> In formating of the page, there is already the World vs North-America
> (A4 vs US letter). Either you designed your template to only use the
> common area, dropping the margin (width 210 vs 216 mm, height 297 vs 279
> mm, so 6 mm & 18 mm of white..), or you didn't and the change of paper
> becomes "interesting" (truncated text, or repaginated with references
> becoming wrong...)
>
> A document is more than a collection of pages.
>
> And remember: your documents will be migrated to the new company logo
> and charts when the bigger corporation buy your company... or resell
> it... or change its visual identity, or want to explore a new market.
>
> Better keep a strict separation between formatting and content. (your
> diagrams & pictures might show the company logo, but it should not be
> copied inside every of them, it should be part of the formatting data
> that can be referenced by them). The company name as well as the product
> name are also not part of the content.
>
>
This.
I happen to work with commercial software packages that were bought,
renamed, and merged multiple times... It makes life interesting when
looking for upgrade logs. I imagine documentation writers must be
having a field day.
--
/*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
|
|
| |
| |
|
|
|
|
| |
|
|
