You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by David Nalley <da...@gnsa.us> on 2012/08/08 00:37:05 UTC
DOCS: problems with using entities
Hi folks.
I experienced a problem today building the docs set now that we have
an entity in place. The problem that I found was: (building with
--format=test succeeds, but specifying a real output fails complaining
about not being able to locate an entity.)
Joe has begun working around this by specifying the entity file in the
XML declaration.
The problem is, that when compiling to a real output format it expects
to find Doc_name.ent - and of course that isn't there. cloudstack.ent
is the only thing present. If there are no declared entities, you
never see a problem. However, publican.cfg declares the name to be:
release-notes-3.0.4, however there are a number of these, so my
supposition is that it's all designed to work with a single set of XML
documents and picking which are included for any given document
produced.
So how do we solve this. symlink a .ent to cloudstack.ent file for
each doc produced? Create a directory to house all of the XML files
and symlink them as appropriate to the document they are to be
included in? Something else?
Thoughts, comments, wisdom welcome.
--David
Re: DOCS: problems with using entities
Posted by Jessica Tomechak <je...@gmail.com>.
>
> -----Original Message-----
> From: Ewan Mellor [mailto:Ewan.Mellor@eu.citrix.com]
> Sent: Tuesday, August 07, 2012 6:02 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: RE: DOCS: problems with using entities
>
> > -----Original Message-----
> > From: Ewan Mellor
> > Sent: Tuesday, August 07, 2012 5:47 PM
> > To: cloudstack-dev@incubator.apache.org
> > Subject: RE: DOCS: problems with using entities
> >
> > > -----Original Message-----
> > > From: David Nalley [mailto:david@gnsa.us]
> > > Sent: Tuesday, August 07, 2012 3:37 PM
> > > To: cloudstack-dev@incubator.apache.org
> > > Subject: DOCS: problems with using entities
> > >
> > > Hi folks.
> > >
> > > I experienced a problem today building the docs set now that we have
> > > an entity in place. The problem that I found was: (building with
> > > --format=test succeeds, but specifying a real output fails
> > complaining
> > > about not being able to locate an entity.)
> > >
> > > Joe has begun working around this by specifying the entity file in
> > the
> > > XML declaration.
> > >
> > > The problem is, that when compiling to a real output format it
> > expects
> > > to find Doc_name.ent - and of course that isn't there.
> > > cloudstack.ent is the only thing present. If there are no declared
> > > entities, you never see a problem. However, publican.cfg declares the
> name to be:
> > > release-notes-3.0.4, however there are a number of these, so my
> > > supposition is that it's all designed to work with a single set of
> > XML
> > > documents and picking which are included for any given document
> > > produced.
> > >
> > > So how do we solve this. symlink a .ent to cloudstack.ent file for
> > > each doc produced? Create a directory to house all of the XML files
> > > and symlink them as appropriate to the document they are to be
> > > included in? Something else?
> >
> > Having release-notes-3.0.4 in the publican.cfg obviously doesn't make
> > any sense. I presume we need multiple publican.cfg files, one for
> > each doc that we want to build.
> >
> > Looking at the Publican docs, symlinking a Doc_name.ent to
> > cloudstack.ent (or something like that) seems like the only sensible
> > option open to us. The Publican docs have a long rant about how what
> > we are doing is evil, but I don't see any alternative.
> >
> > Ewan.
> >
> > http://docs.fedoraproject.org/en-
> > US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-
> > Users_Guide-Creating_a_document.html#sect-Users_Guide-
> > Files_in_the_book_directory-Doc_Name.ent
>
> By the way, I created a Jenkins job that runs Publican. So now we know
> automatically and reliably that it doesn't work right now.
>
> http://jenkins.cloudstack.org/job/build-docs-master/
>
> Ewan.
>
>
Ewan,
Thanks very much for making a build job. I just broke it even more. It will
start to work better if you make it use the new publican-all.cfg.
Jessica T.
CloudStack Tech Pubs
RE: DOCS: problems with using entities
Posted by Ewan Mellor <Ew...@eu.citrix.com>.
> -----Original Message-----
> From: Ewan Mellor
> Sent: Tuesday, August 07, 2012 5:47 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: RE: DOCS: problems with using entities
>
> > -----Original Message-----
> > From: David Nalley [mailto:david@gnsa.us]
> > Sent: Tuesday, August 07, 2012 3:37 PM
> > To: cloudstack-dev@incubator.apache.org
> > Subject: DOCS: problems with using entities
> >
> > Hi folks.
> >
> > I experienced a problem today building the docs set now that we have
> > an entity in place. The problem that I found was: (building with
> > --format=test succeeds, but specifying a real output fails
> complaining
> > about not being able to locate an entity.)
> >
> > Joe has begun working around this by specifying the entity file in
> the
> > XML declaration.
> >
> > The problem is, that when compiling to a real output format it
> expects
> > to find Doc_name.ent - and of course that isn't there. cloudstack.ent
> > is the only thing present. If there are no declared entities, you
> > never see a problem. However, publican.cfg declares the name to be:
> > release-notes-3.0.4, however there are a number of these, so my
> > supposition is that it's all designed to work with a single set of
> XML
> > documents and picking which are included for any given document
> > produced.
> >
> > So how do we solve this. symlink a .ent to cloudstack.ent file for
> > each doc produced? Create a directory to house all of the XML files
> > and symlink them as appropriate to the document they are to be
> > included in? Something else?
>
> Having release-notes-3.0.4 in the publican.cfg obviously doesn't make
> any sense. I presume we need multiple publican.cfg files, one for each
> doc that we want to build.
>
> Looking at the Publican docs, symlinking a Doc_name.ent to
> cloudstack.ent (or something like that) seems like the only sensible
> option open to us. The Publican docs have a long rant about how what
> we are doing is evil, but I don't see any alternative.
>
> Ewan.
>
> http://docs.fedoraproject.org/en-
> US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-
> Users_Guide-Creating_a_document.html#sect-Users_Guide-
> Files_in_the_book_directory-Doc_Name.ent
By the way, I created a Jenkins job that runs Publican. So now we know automatically and reliably that it doesn't work right now.
http://jenkins.cloudstack.org/job/build-docs-master/
Ewan.
Re: DOCS: problems with using entities
Posted by Jessica Tomechak <je...@gmail.com>.
>
>
> -----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Wednesday, August 08, 2012 6:12 AM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: DOCS: problems with using entities
>
> On Wed, Aug 8, 2012 at 2:40 AM, Radhika Puthiyetath <
> radhika.puthiyetath@citrix.com> wrote:
> > Hi David,
> >
> > Here is the readme file that Jessica created for generating various book
> set from the XML files.
> >
> > The readme has the complete information on generating different book
> sets by appropriately declaring in the .cfg file.
> >
> > Regards
> > -Radhika
>
> I understand what the intent is, it's just failing now that we have added
> entities to the mix.
>
> Ewan: The build now works in jenkins. Sadly, symlinks don't, for whatever
> reason. (work fine on my local machine, but not on jenkins
> itself) I had to instantiate a real file for it to build.
>
> --David
>
For release 4.0, I am not sure we need to create separate "books". It
should be sufficient to generate the entire docs directory using
publican-all.cfg. Then we will have one document that contains "chapters"
on installation, administration, developer's info, and so on.
I had just started to work on setting up the repo for automated builds of
multiple books. You can see some of my first attempts in the configs
subdirectory under docs, where I was saving my working files during testing
(before David kindly moved the docs files over to the Apache repo). I
should probably delete that directory now.
I have just added six new publican.cfg files named for the "books" they
create: publican-install.cfg, publican-devguide.cfg, etc. I am not sure
whether this can be done to create Book_Info_Install,
cloudstack-install.ent, and so on for each "book." I haven't tested it.
Publican does offer a couple of techniques for generating what they call
"book sets," but I don't think either technique will work. Option #1 works
only with svn, so that isn't a fit for us. Option #2 seems to assume that
the content of the books doesn't overlap, and that is definitely not a fit
for us. We need to come up with something clever.
I'm glad to see more attention focusing on this task. Please keep sending
ideas!
Jessica T.
CloudStack Tech Pubs
Re: DOCS: problems with using entities
Posted by David Nalley <da...@gnsa.us>.
On Wed, Aug 8, 2012 at 2:40 AM, Radhika Puthiyetath
<ra...@citrix.com> wrote:
> Hi David,
>
> Here is the readme file that Jessica created for generating various book set from the XML files.
>
> The readme has the complete information on generating different book sets by appropriately declaring in the .cfg file.
>
> Regards
> -Radhika
I understand what the intent is, it's just failing now that we have
added entities to the mix.
Ewan: The build now works in jenkins. Sadly, symlinks don't, for
whatever reason. (work fine on my local machine, but not on jenkins
itself) I had to instantiate a real file for it to build.
--David
RE: DOCS: problems with using entities
Posted by Radhika Puthiyetath <ra...@citrix.com>.
Hi David,
Here is the readme file that Jessica created for generating various book set from the XML files.
The readme has the complete information on generating different book sets by appropriately declaring in the .cfg file.
Regards
-Radhika
-----Original Message-----
From: David Nalley [mailto:david@gnsa.us]
Sent: Wednesday, August 08, 2012 4:07 AM
To: cloudstack-dev@incubator.apache.org
Subject: DOCS: problems with using entities
Hi folks.
I experienced a problem today building the docs set now that we have an entity in place. The problem that I found was: (building with --format=test succeeds, but specifying a real output fails complaining about not being able to locate an entity.)
Joe has begun working around this by specifying the entity file in the XML declaration.
The problem is, that when compiling to a real output format it expects to find Doc_name.ent - and of course that isn't there. cloudstack.ent is the only thing present. If there are no declared entities, you never see a problem. However, publican.cfg declares the name to be:
release-notes-3.0.4, however there are a number of these, so my supposition is that it's all designed to work with a single set of XML documents and picking which are included for any given document produced.
So how do we solve this. symlink a .ent to cloudstack.ent file for each doc produced? Create a directory to house all of the XML files and symlink them as appropriate to the document they are to be included in? Something else?
Thoughts, comments, wisdom welcome.
--David
Re: DOCS: problems with using entities
Posted by Jessica Tomechak <je...@gmail.com>.
>
> -----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Tuesday, August 07, 2012 9:39 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: DOCS: problems with using entities
>
> On Tue, Aug 7, 2012 at 10:11 PM, Joe Brockmeier <jz...@zonker.net> wrote:
> > On Wed, Aug 08, 2012 at 01:47:25AM +0100, Ewan Mellor wrote:
> >> Looking at the Publican docs, symlinking a Doc_name.ent to
> >> cloudstack.ent (or something like that) seems like the only sensible
> option open to us.
> >> The Publican docs have a long rant about how what we are doing is
> >> evil, but I don't see any alternative.
> >
> > So, I see the point given against using entities for something like a
> > product / project name, but... it seems to me that if we have a
> > situation where "Apache CloudStack" or "CloudStack" could be
> > translated to a language that has several forms, the clued-in
> > translator could be given leeway to change &PRODUCT; to whatever the
> > proper form of CloudStack would be.
> >
>
>
> I don't. Jeff and I disagree on this particular point along with several
> other things in the use of Publican. CloudStack and Apache CloudStack are
> trademarks, we don't want them translated IMO.
>
> --David
>
The reason to use an entity for the product name is to make it easy to
rebrand the documentation. As I understand it, one goal in Apache is to let
people grab the code and go use it to create something else (correct me if
I'm wrong on that).
In general, I'm in favor of constructing the documentation so that it's
easy to reuse and customize.
I also agree with David that the term CloudStack shouldn't be translated.
It's not translated in the Japanese docs that we already have.
Jessica T.
CloudStack Tech Pubs
Re: DOCS: problems with using entities
Posted by David Nalley <da...@gnsa.us>.
On Tue, Aug 7, 2012 at 10:11 PM, Joe Brockmeier <jz...@zonker.net> wrote:
> On Wed, Aug 08, 2012 at 01:47:25AM +0100, Ewan Mellor wrote:
>> Looking at the Publican docs, symlinking a Doc_name.ent to cloudstack.ent
>> (or something like that) seems like the only sensible option open to us.
>> The Publican docs have a long rant about how what we are doing is evil,
>> but I don't see any alternative.
>
> So, I see the point given against using entities for something like a
> product / project name, but... it seems to me that if we have a
> situation where "Apache CloudStack" or "CloudStack" could be translated
> to a language that has several forms, the clued-in translator could be
> given leeway to change &PRODUCT; to whatever the proper form of
> CloudStack would be.
>
I don't. Jeff and I disagree on this particular point along with
several other things in the use of Publican. CloudStack and Apache
CloudStack are trademarks, we don't want them translated IMO.
--David
Re: DOCS: problems with using entities
Posted by Joe Brockmeier <jz...@zonker.net>.
On Wed, Aug 08, 2012 at 01:47:25AM +0100, Ewan Mellor wrote:
> Looking at the Publican docs, symlinking a Doc_name.ent to cloudstack.ent
> (or something like that) seems like the only sensible option open to us.
> The Publican docs have a long rant about how what we are doing is evil,
> but I don't see any alternative.
So, I see the point given against using entities for something like a
product / project name, but... it seems to me that if we have a
situation where "Apache CloudStack" or "CloudStack" could be translated
to a language that has several forms, the clued-in translator could be
given leeway to change &PRODUCT; to whatever the proper form of
CloudStack would be.
For languages where CloudStack would be perfectly acceptable, then
&PRODUCT; could be left as-is.
That is, of course, if we are OK with CloudStack being translated at
all. I'd love to know how other Apache projects handle this particular
situation.
--
Joe Brockmeier
http://dissociatedpress.net/
Twitter: @jzb
RE: DOCS: problems with using entities
Posted by Ewan Mellor <Ew...@eu.citrix.com>.
> -----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Tuesday, August 07, 2012 3:37 PM
> To: cloudstack-dev@incubator.apache.org
> Subject: DOCS: problems with using entities
>
> Hi folks.
>
> I experienced a problem today building the docs set now that we have
> an entity in place. The problem that I found was: (building with
> --format=test succeeds, but specifying a real output fails complaining
> about not being able to locate an entity.)
>
> Joe has begun working around this by specifying the entity file in the
> XML declaration.
>
> The problem is, that when compiling to a real output format it expects
> to find Doc_name.ent - and of course that isn't there. cloudstack.ent
> is the only thing present. If there are no declared entities, you
> never see a problem. However, publican.cfg declares the name to be:
> release-notes-3.0.4, however there are a number of these, so my
> supposition is that it's all designed to work with a single set of XML
> documents and picking which are included for any given document
> produced.
>
> So how do we solve this. symlink a .ent to cloudstack.ent file for
> each doc produced? Create a directory to house all of the XML files
> and symlink them as appropriate to the document they are to be
> included in? Something else?
Having release-notes-3.0.4 in the publican.cfg obviously doesn't make any sense. I presume we need multiple publican.cfg files, one for each doc that we want to build.
Looking at the Publican docs, symlinking a Doc_name.ent to cloudstack.ent (or something like that) seems like the only sensible option open to us. The Publican docs have a long rant about how what we are doing is evil, but I don't see any alternative.
Ewan.
http://docs.fedoraproject.org/en-US/Fedora_Contributor_Documentation/1/html/Users_Guide/chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory-Doc_Name.ent
RE: DOCS: problems with using entities
Posted by Ewan Mellor <Ew...@eu.citrix.com>.
> -----Original Message-----
> From: Joe Brockmeier [mailto:jzb@zonker.net]
> Sent: 07 August 2012 18:58
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: DOCS: problems with using entities
>
>[Snip]
>
> I don't think it'll matter what the publican.cfg declares as long as the XML files
> have the pointer to cloudstack.ent
But I assume that the declaration in publican.cfg determines the top-level XML file, so we still need multiple publican.cfgs because we have multiple books. Don't we?
Ewan.
Re: DOCS: problems with using entities
Posted by David Nalley <da...@gnsa.us>.
On Tue, Aug 7, 2012 at 9:58 PM, Joe Brockmeier <jz...@zonker.net> wrote:
> On Tue, Aug 07, 2012 at 06:37:05PM -0400, David Nalley wrote:
>> Hi folks.
>>
>> I experienced a problem today building the docs set now that we have
>> an entity in place. The problem that I found was: (building with
>> --format=test succeeds, but specifying a real output fails complaining
>> about not being able to locate an entity.)
>
> Yes. I think the problem is actually that some files do not have a DTD
> at all. So they don't tell Publican to look for cloudstack.ent.
I thought that was the problem, so I added a DTD with a pointer to
cloudstack.ent to the few files missing it - and that allows it to
pass the --format=test build. But when it actually goes to output in
something other than test, it still fails. I created a symlink and it
seems to work locally. I'll reclone tomorrow and see why it is still
failing on jenkins.
--David
Re: DOCS: problems with using entities
Posted by Joe Brockmeier <jz...@zonker.net>.
On Tue, Aug 07, 2012 at 06:37:05PM -0400, David Nalley wrote:
> Hi folks.
>
> I experienced a problem today building the docs set now that we have
> an entity in place. The problem that I found was: (building with
> --format=test succeeds, but specifying a real output fails complaining
> about not being able to locate an entity.)
Yes. I think the problem is actually that some files do not have a DTD
at all. So they don't tell Publican to look for cloudstack.ent.
When I started doing the license clean up, some of the files had no DTD
at all - so I thought that was because they were pulled into other files
as includes and didn't need the DTD. That seems to be an error on my
part - so once I finish licensing & fixing the DTDs in the rest of the
files on my list, I'll go back and make sure that they all have the proper
DTD.
> The problem is, that when compiling to a real output format it expects
> to find Doc_name.ent - and of course that isn't there. cloudstack.ent
> is the only thing present. If there are no declared entities, you
> never see a problem. However, publican.cfg declares the name to be:
> release-notes-3.0.4, however there are a number of these, so my
> supposition is that it's all designed to work with a single set of XML
> documents and picking which are included for any given document
> produced.
I don't think it'll matter what the publican.cfg declares as long as the
XML files have the pointer to cloudstack.ent
> So how do we solve this. symlink a .ent to cloudstack.ent file for
> each doc produced? Create a directory to house all of the XML files
> and symlink them as appropriate to the document they are to be
> included in? Something else?
I'll fix the missing DTD/ENTITY declaration and make sure everything
compiles. That should leave us in good shape unless I've missed
something.
--
Joe Brockmeier
http://dissociatedpress.net/
Twitter: @jzb