Bug 427481 (publican) - Review Request: publican - publication tool chain
Summary: Review Request: publican - publication tool chain
Keywords:
Status: CLOSED NEXTRELEASE
Alias: publican
Product: Fedora
Classification: Fedora
Component: Package Review
Version: rawhide
Hardware: All
OS: Linux
medium
medium
Target Milestone: ---
Assignee: Jens Petersen
QA Contact: Fedora Extras Quality Assurance
URL:
Whiteboard:
Depends On: 427479 427480
Blocks: 427482
TreeView+ depends on / blocked
 
Reported: 2008-01-04 03:43 UTC by Jeff Fearn ๐Ÿž
Modified: 2013-06-07 12:44 UTC (History)
18 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2008-02-13 07:17:06 UTC
Type: ---
Embargoed:
kwade: fedora_requires_release_note-
petersen: fedora-review+


Attachments (Terms of Use)
proposed documentation-devil logo from teh community (27.92 KB, image/png)
2008-01-14 19:16 UTC, Joshua Wulf
no flags Details
One does not simply "name a package in Fedora", just as... (107.84 KB, image/jpeg)
2008-01-15 01:04 UTC, Joshua Wulf
no flags Details
project image (34.40 KB, image/png)
2008-01-15 01:18 UTC, Andy Fitzsimon
no flags Details
sparta (192.01 KB, image/png)
2008-01-15 01:41 UTC, Christopher Curran
no flags Details
documentation-devil.spec-1.patch (5.66 KB, patch)
2008-01-16 08:00 UTC, Jens Petersen
no flags Details | Diff
documentation-devil.spec-xsl.patch (972 bytes, patch)
2008-01-21 06:02 UTC, Jens Petersen
no flags Details | Diff
publican.spec-1.patch (844 bytes, patch)
2008-02-07 16:11 UTC, Jens Petersen
no flags Details | Diff
publican.spec-2.patch (2.41 KB, patch)
2008-02-12 04:43 UTC, Jens Petersen
no flags Details | Diff
publican.spec-3.patch (1.52 KB, patch)
2008-02-12 06:49 UTC, Jens Petersen
no flags Details | Diff

Description Jeff Fearn ๐Ÿž 2008-01-04 03:43:45 UTC
Spec URL: http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devel.spec

SRPM URL: http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devel-0.26-1.fc9.src.rpm

Description: Tool chain to convert DocBook XML in to multiple output formats.

Comment 1 Huzaifa S. Sidhpurwala 2008-01-04 06:40:45 UTC
This what rpmlint has to say:
[root@dhcp1-17 ~]# rpmlint documentation-devel-0.26-1.fc9.src.rpm 
documentation-devel.src: W: invalid-license GPL

I feel GPL+ is a better option.

Comment 2 Jens Petersen 2008-01-04 09:21:31 UTC
I feel the name is a bit too generic.

How about something like docbook-build-tools?

Comment 3 Jeff Fearn ๐Ÿž 2008-01-06 23:12:45 UTC
(In reply to comment #1)
> This what rpmlint has to say:
> [root@dhcp1-17 ~]# rpmlint documentation-devel-0.26-1.fc9.src.rpm 
> documentation-devel.src: W: invalid-license GPL
> 
> I feel GPL+ is a better option.

Spec file updated.

Comment 4 Parag AN(เคชเคฐเคพเค—) 2008-01-07 11:48:42 UTC
jfearn,
  Can you make package name to docbook-build-tools?

Comment 5 Jeff Fearn ๐Ÿž 2008-01-07 22:37:58 UTC
(In reply to comment #4)
> jfearn,
>   Can you make package name to docbook-build-tools?

This system is being used in production systems within Red Hat and has been for
some time. It would take a very well presented argument to get me to consider
renaming this package.

Cheers, Jeff.

Comment 6 Patrice Dumas 2008-01-07 22:45:49 UTC
What kind of argument? It is much too generic. The package
name space has to be shared by all the packages and there are 
a lot of packages that could have that name.

Comment 7 Michael Hideo 2008-01-07 23:18:29 UTC
Jeff/Patrice,

Any way to tell if anyone else is using that name? 

- Mike

Comment 8 Patrice Dumas 2008-01-07 23:28:33 UTC
No way. But it isn't a reason to begin to use too generic
names.

Comment 9 Michael Hideo 2008-01-08 23:52:54 UTC
Guys,

What is the precedence for renaming a community package and the naming guidelines? 

- Mike

Comment 10 Jens Petersen 2008-01-09 04:29:02 UTC
I guess docbook-build-tools wouldn't be an good name anyway...

Having thought a little more about it and looked at the package more
here are my thoughts on the naming:
- first I think the initial reaction to the name from the Fedora point
  of view is that there are problems with both words in the name:
- "documentation" is vague: it can refer to many different things ranging
  from readme files under %doc, to manpages, to info or html included in the
  source (which might one day be generated using this package if they care for
  docbook), or manuals in docbook which I think is the main target of this
  package: we have lacked good documentation in Fedora to date. :)
- the "devel" suffix is usually not used for tools but subpackages of libraries
  with development files associated with C libraries, etc.
- I looked at our package naming guidelines and they were vague on this case.

But to give an extreme example it is a little like starting a new project
for a browser (or an editor) and calling it "browser" (or "editor").
"documentation-devel" is better than that of course, but naively it seems
it could be made a bit less generic without loosing its generality.

I understand the Red Hat Docs team have been using this package name internally
for several years and are pretty comfortable with it, and that you want to keep
this package generic (in the sense of commodity) to encourage others in the
community outside Fedora to use it for their international documentation needs.

If renaming the newly open-sourced project upstream is not an option
I might suggest at least adding some suffix, eg documentation-devel-tools,
to make the name slightly less generic.  I think it would be ok for the
package to obsolete or provide documentation-devel for backward compatibility
if necessary.

It might help also to see an example package that shows how it would
be used to get a better idea about it.  And to hear of about any plans 
to push documentation to fedora, etc to get a bigger picture. :)

If this package is positioned as the cornerstone of our documentation
infrastructure it might still be reasonable to keep a pretty general name.

Comment 11 Jens Petersen 2008-01-09 04:38:09 UTC
If the license is actually "GPL 2 or later", the license tag should be "GPLv2+".

docbook-xsl is big and it should really be in a separate package IMHO.

Comment 12 Patrice Dumas 2008-01-09 08:26:58 UTC
The upstream name is not right to begin with. I don't know about
a precedent, but I myself ask upstream to change their name when it is
to short or too generic (I did that for g2lib, so far they haven't 
acted, but I did what I could). I also made that recommendation for ht.

But here it is easily done since you are also upstream. The name
of the package is part of the 'quality' of the package and having
a name too generic seems to be to me a good enough reason not to
include it in fedora. There are no precise guidelines about what
makes a package unsuitable for inclusion in fedora (except for license
guidelines), but having a package that abuses the shared 
namespaces (package name, library name, binary in /usr/bin name)
is in my opinion a reason sufficient to block a release if upstream is
under the fedora umbrella.

In any case please try to think at your software name from the 
perspective of free software community (other developers and 
users) and ask yourself, is my package rightly named?

Comment 13 Michael Hideo 2008-01-10 02:31:06 UTC
(In reply to comment #12)
> The upstream name is not right to begin with. I don't know about
> a precedent, but I myself ask upstream to change their name when it is
> to short or too generic (I did that for g2lib, so far they haven't 
> acted, but I did what I could). I also made that recommendation for ht.
> 
> But here it is easily done since you are also upstream. The name
> of the package is part of the 'quality' of the package and having
> a name too generic seems to be to me a good enough reason not to
> include it in fedora. There are no precise guidelines about what
> makes a package unsuitable for inclusion in fedora (except for license
> guidelines), but having a package that abuses the shared 
> namespaces (package name, library name, binary in /usr/bin name)
> is in my opinion a reason sufficient to block a release if upstream is
> under the fedora umbrella.
> 
> In any case please try to think at your software name from the 
> perspective of free software community (other developers and 
> users) and ask yourself, is my package rightly named?

Hi Patrice/Jens,

Currently the documentation-devel project is #2 in google's pageranking.

Additionally, as requested, here is a link to the project page:
https://fedorahosted.org/documentation-devel

Based on the google page ranking metric and the provision of additional project
documentation for your review, we formally request the preservation of the
documentation-devel name for this project.

Best regards,
Mike


Comment 14 Patrice Dumas 2008-01-10 08:53:28 UTC
(In reply to comment #13)

> Currently the documentation-devel project is #2 in google's pageranking.

So what? It is not relevant to the shared named space issue.
It may mean that, fortunately nobody else did a package with
such a generic name.

I'd say what I said above since you didn't really took it into 
account:
In any case please try to think at your software name from the 
perspective of free software community (other developers and 
users) and ask yourself, is my package rightly named?


Comment 15 Joshua Wulf 2008-01-10 15:19:36 UTC
Hey guys, I've been following the conversation on this package. I've been using
it on Fedora for the past year and a half.

A couple of things:

1) Open sourcing this package and contributing it to Fedora will be of great
benefit for the state of Fedora documentation. Basically this is the toolchain
that is used to produce RHEL and JBoss documentation. 

It is a mature project with a significant existing community of users, who have
it embedded in their enterprise infrastructure. 

Changing the name is not a trivial exercise - the impact is quite high, and open
source projects, even commercial ones, are not known for having resources to spare.

This isn't in itself a reason to retain the name in Fedora, but it gives some
context to jfearn's concern. 

2) In terms of the suitability of the name for the package - I agree that what
we're looking at here is a canonical name - like "kernel" or "NetworkManager".

I think that we can make a case for this package to have the canonical name. 

There is a missing infrastructure piece for development of documentation for
open source software. The fact that this name space is vacant apart from this
package indicates the necessity of such a piece. It also indicates that this
package speaks strongly to this need, perhaps sufficiently now to answer it,
perhaps with some further work. At the very least it is a significant starting
point.

The package brings together an end-to-end opensource toolchain that allows open
source projects to produce professional documentation, taking several forms of
input and outputting html, pdf, manpages, xml, and several other formats. 

It produces branded documentation using templates.

It handles multiple language translations.

It's been developed over a number of years and is used in an enterprise setting.

Basically it provides the whole kit and caboodle for professional open source
documentation production from source. In terms of Fedora it provides a missing
infrastructure piece for documentation production and translations.

In terms of the wider scene it provides a missing infrastructure piece, and so I
think that a canonical name is not out of place. Red Hat / Fedora have a history
of providing significant plumbing pieces to the community (like NetworkManager).

I think we have a good case for retaining the canonical name, because with this
package we have a good, clear shot at the title.

Take a look at what it can do, how extensible it is, and where it fits into an
existing gap in the infrastructure scene, and see what you think.

Comment 16 Patrice Dumas 2008-01-10 15:54:57 UTC
No problem, if you find a reviewer who accepts this name, then fine.

I still find that it is a bad name. Saying that there are other names
that are badly chosen won't change that. This one especially badly
chosen, moreover, in the context of fedora since -devel is consistently
used for sub packages headers and .so files used for linking. But, hey
that's just my advice.

Comment 17 Parag AN(เคชเคฐเคพเค—) 2008-01-10 16:11:37 UTC
Good to have this discussed on fedora-devel then.

Comment 18 Jens Petersen 2008-01-11 00:33:31 UTC
As per comment 11, I strongly recommend creating a separate package for
docbook-xsl and making this review depend on it so as not to further delay
this review.

It may be worth raising the naming issue on fedora-packaging list.



Comment 19 Jeff Fearn ๐Ÿž 2008-01-11 01:14:02 UTC
(In reply to comment #18)
> As per comment 11, I strongly recommend creating a separate package for
> docbook-xsl and making this review depend on it so as not to further delay
> this review.

This package is dependent on this exact version of the xsl and is smaller than
many source packages currently in Fedora. 

see:
http://download.fedora.redhat.com/pub/fedora/linux/development/source/SRPMS/

> It may be worth raising the naming issue on fedora-packaging list.

I think that whole discussion is ridiculous, pointless and a complete waste of
time. I'll see if I can convince the manager in question to reconsider this push.


Comment 20 Jens Petersen 2008-01-11 01:55:08 UTC
> This package is dependent on this exact version of the xsl and is smaller than
> many source packages currently in Fedora. 

I see, ok - I think I overestimated the size going by its inflated size (36MB).

Generally it would be better to use a system package rather than carrying your
own copy of it, but if it is really necessary perhaps an exception can be made
for now since at least it is not a binary library.

> I think that whole discussion is ridiculous, pointless and a complete waste of
> time.

Well it may seem so to people outside the fedora packaging project,
but making an OS is a serious business.  With over 5000 packages currently
in the distro we need some rules and conventions to prevent pollution
of the namespaces.  Learning and accepting those conventions is a requisite
to joining and working with the project.  However I point out that no
final decision on the name has been made yet, it is still under discussion.

Comment 21 Parag AN(เคชเคฐเคพเค—) 2008-01-11 02:04:21 UTC
(In reply to comment #19)
> (In reply to comment #18)
> > As per comment 11, I strongly recommend creating a separate package for
> > docbook-xsl and making this review depend on it so as not to further delay
> > this review.
> 
> This package is dependent on this exact version of the xsl and is smaller than
> many source packages currently in Fedora. 
> 
> see:
> http://download.fedora.redhat.com/pub/fedora/linux/development/source/SRPMS/
> 
> > It may be worth raising the naming issue on fedora-packaging list.
> 
> I think that whole discussion is ridiculous, pointless and a complete waste of
> time. I'll see if I can convince the manager in question to reconsider this push.
> 
  I don't think so. If people will start thinking and implementing their own
packaging guidelines then we don't need any policies/committees to discuss any
issues in fedora. Saying so I think question has been raised on fedora's work,
its policies.


Comment 22 Michael Hideo 2008-01-11 02:48:10 UTC
(In reply to comment #19)
> (In reply to comment #18)
> > As per comment 11, I strongly recommend creating a separate package for
> > docbook-xsl and making this review depend on it so as not to further delay
> > this review.
> 
> This package is dependent on this exact version of the xsl and is smaller than
> many source packages currently in Fedora. 
> 
> see:
> http://download.fedora.redhat.com/pub/fedora/linux/development/source/SRPMS/
> 
> > It may be worth raising the naming issue on fedora-packaging list.
> 
> I think that whole discussion is ridiculous, pointless and a complete waste of
> time. I'll see if I can convince the manager in question to reconsider this push.
> 

Hey, Jeff. 

It's cool. We'll get it sorted out. 

I really appreciate everything you have done for open-source in the last 3
years. You have created a toolchain that has enabled the 48 folks using it to
generate more open-source content than any other project in the history of
open-source. You have done things that no-one else has done and you did so
without ever drawing attention to yourself and your immense contributions.

There are a 179 make files that need to be edited and 4117 documentation sets in
23 languages that need to be recompiled. I know it is non-trivial and a world of
work to re-do 2 years worth of work in 2 days.

Let me check the community of use around the documentation-devel package and see
what their thougths are on taking this burden completely on themselves to redo.

Thank you again, Jeff and apologies to the Jens/Patrice/Parang for the
distraction. Honestly had no idea the impact this name would have on fedora.

- Mike

Comment 23 Murray McAllister 2008-01-11 03:18:36 UTC
I think this is a tribute to how great Jeff's package actually is. No one is
complaining that 'the package does not do this', or 'if I run this command it
breaks everything', no, people are just complaining about the name.

If this happens everytime someone wants to push a package into Fedora, then it's
a good thing Red Hat does not, and never will, control open source, otherwise
nothing would ever be released, and everyone would debate package names all day :(

Not that it matters what I think, but I think if it was pushed into Fedora, then
a few people would start using it and see how great it is, the word would
spread, and no one could care what the name is.

If documentation-devel is such a horrible name, run "rpm -qa" and see what else
is allowed.

Thanks,

Murray.

Comment 24 Andy Fitzsimon 2008-01-11 03:23:18 UTC
I do not find the naming dilemma to be an issue.

Given the google juice the phrase documentation devel already has and the
specialized nature of the package, any name will work.

This is a tool Intended for technical documentation developers (not first time
FOSS users) so we really have no blocking need to specify a brandable project name.

That said, I would have supported renaming had it been a trivial move, but I see
it will not cause great enough a confusion to warrant its non-inclusion from F9
on this grounds.

What would greatly disappoint, is not getting this package into Fedora 9. 

documentation-devel could greatly serve the content community by bringing a
quality publishing tool to books for many free software projects.

I know both inkscape and gimp documentation certainly need the improvements this
package can offer. 

The name space is free, the tool is useful lets get this innovation to the
fedora community ASAP.


Comment 25 Isaac Rooskov 2008-01-11 03:38:07 UTC
Personally I, like everyone else here, believes that this package will be a
great asset to the open-source community and that in the end the name (though I
understand and respect convention) probably isn't going to be the largest concern. 

It's a tool for creating and developing professional documentation and if the
name at the moment isn't considered fitting then I propose that the name should
be simple and clearly relate to the product. 

DocCommander, DocTools, something simple and easy to remember. 

The most important thing I can see though is to actaully release the package
into the open source community so as long as it gets there, sooner rather than
later, the name doesn't seem that important to me personally.  

Comment 26 Warren Togami 2008-01-11 03:53:13 UTC
> If this happens everytime someone wants to push a package into Fedora,

This is a gross misrepresentation of reality.  The vast majority of package
reviews go through without the need to consult a committee for clarification or
advice.

> What would greatly disappoint, is not getting this package into Fedora 9.

Nobody is disputing this fact.  Furthermore, it would likely be easy to get it
into F8 immediately after review approval too.

Have you considered the possibility that this desired name really is problematic
for the global community namespace?  It especially feels wrong to me because it
clashes with the long established convention of *-devel for library header
packages.  We have always tried to avoid requiring any *-devel package for
non-development (usually meaning building binaries) operation.

I understand the desire to keep the name used internally for years, but is it
really such a huge burden to choose a different name?

My personal opinion: *anything* that isn't *-devel is fine.

Comment 27 David O'Brien 2008-01-11 03:58:53 UTC
I don't see the name as a huge issue either. Admittedly I've been bitten by
oddly named packages in the past, but I just learn and continue. Given the
traction that this package has already, and the effort required to rename it, I
suggest leaving it as-is.

Comment 28 Chester Cheng 2008-01-11 04:09:12 UTC
As long as it works, the name is not an issue to me at all.

Comment 29 Parag AN(เคชเคฐเคพเค—) 2008-01-11 04:13:59 UTC
As discussed on IRC with Warren, good to name this package as DocumentationKit

Comment 30 Warren Togami 2008-01-11 04:37:19 UTC
*-devel is treated special in a few ways:

- It is *wrong* for runtime packages to depend on *-devel packages.  *-devel
packages are for We fix bugs like that in the distro all the time.
- rpmdev-rmdevelrpms attempts to remove *-devel for this purpose.
- *-devel is special in that it is assumed to be multilib by the repository
creation tools.

Is it really a huge amount of effort to rename it?
Is simple string search and replace to a new name really such a huge burden?

I suggested DocumentationKit as a possible good name.  It satisfies both the
*-devel problem and "documentation" genericness namespace issue, and it goes
along with the other StudyCaps names ending in *Kit.

Perhaps you could think of a better name.  But PLEASE don't use *-devel.

Comment 31 Lana Brindley 2008-01-11 04:43:11 UTC
The main arguments against documentation-devel seem to be that it is "too
generic" and doesn't fit existing convention.

Being "too generic" is not, in this case, necessarily a bad thing.
Documentation-devel is a very broad tool. Not only is it broad now, but it has
the capacity to become even broader. The name is certainly canonical, as jwulf
stated, but so it should be - no other tool exists that is like it (afaik).

Convention is rather a loose term - particularly in FOSS. The existing
documentation on what is considered 'conventional' varies greatly from project
to project and, as mentioned by jens peterson in comment #10 "our package naming
guidelines ... were vague on this case." With that in mind, documentation-devel
is a set of tools for the development of documentation - this seems logical to me.

Add to this the fact that the name is not being used, the fact that the name is
commonly known in the society (evidenced by the Google ranking) and the fact
that it has been used under this name for a lengthy period of time. 

Having a 'too generic' name could impact some users, most though would search on
the term 'Documentation' and, through great Google rankings, will find the tool
they're after. Changing the name at this stage *will* negatively impact a large
body of users. From a cost/benefit perspective, having a 'too generic' name is a
small price to pay.

Perhaps we should be concentrating on the tool and not the name. It is a
fantastic tool that I have been using for nearly six months now, and from the
feedback I have had there is a definite need for it to be released to the wider
community. We all owe a debt of gratitude to jfearn, not the injustice of
squabbling over the name of the thing. 

The principal of FOSS is that we all get to take part in the development and use
of tools that simply wouldn't be available otherwise. Why are we getting hung up
because a name is "too generic"?

The tool works, and the community want it. Let's concentrate on getting it out
there and we can bicker over it later.

Comment 32 Warren Togami 2008-01-11 04:56:07 UTC
Convention to me is even a bigger reason than genericness.  As described above
there are REAL technical reasons why the *-devel convention makes this a very
poor package name.

I personally don't care about the genericness part.  I do care about the *-devel
convention.  Please choose anything else.

Furthermore, I have yet to see a legitimate reason why renaming this package
would be such a burden beyond the emotional desire to keep it only because it
was named such internally in the past.

Comment 33 Michael Hideo 2008-01-11 06:06:21 UTC
(In reply to comment #30)
> *-devel is treated special in a few ways:
> 
> - It is *wrong* for runtime packages to depend on *-devel packages.  *-devel
> packages are for We fix bugs like that in the distro all the time.

I think I understand the point of view. This documentation-devel package is used
to development documentation rpms. In that sense, documentation-devel is not the
 runtime, but contains the files needed for you to develop the resulting runtime
(documentation). Whether it is developing code or words, it is all poetry.



Comment 34 Isaac Rooskov 2008-01-11 06:19:04 UTC
(In reply to comment #33)
>Whether it is developing code or words, it is all poetry.
> 
Ah poetry, is there anything more beautiful? Anyway, I understand the POV that
you're coming from and in that sense it is nice 



Comment 35 Rahul Sundaram 2008-01-11 07:35:21 UTC
Even if packages are used for development, they cannot end with "-devel". It is
called gcc and not gcc-devel for example. Besides they are numerous occasions
where a package that ends with "-devel" is excluded. A few examples

http://fedoraproject.org/wiki/QA/8/FinalTreeTesting

"Make sure default install doesn't include -devel packages"

Look at the default kickstart files that are used to generate the GNOME and KDE
live images. They automatically exclude *-devel. In short any package that ends
with -devel is assumed to contain development files (headers et all) and not
development tools in various places throughout Fedora and making an exception
just for this package is unwieldy. You just have to call it something else. 

Comment 36 Till Maas 2008-01-11 09:54:40 UTC
(In reply to comment #33)

> I think I understand the point of view. This documentation-devel package is used
> to development documentation rpms. In that sense, documentation-devel is not the
>  runtime, but contains the files needed for you to develop the resulting runtime
> (documentation). Whether it is developing code or words, it is all poetry.

Hoy about rpmdev-doctools as a new name? There is also a rpmdev-tools package in
Fedora, which is afaik developed by Fedora maintainers.

Comment 37 Michael Hideo 2008-01-11 10:29:30 UTC
(In reply to comment #35)
> Even if packages are used for development, they cannot end with "-devel". It is
> called gcc and not gcc-devel for example. Besides they are numerous occasions
> where a package that ends with "-devel" is excluded. A few examples
> 
> http://fedoraproject.org/wiki/QA/8/FinalTreeTesting
> 
> "Make sure default install doesn't include -devel packages"
> 
> Look at the default kickstart files that are used to generate the GNOME and KDE
> live images. They automatically exclude *-devel. In short any package that ends
> with -devel is assumed to contain development files (headers et all) and not
> development tools in various places throughout Fedora and making an exception
> just for this package is unwieldy. You just have to call it something else. 

Thank you Rahul, 

Excellent read and I understand that now. It is okay not to include this in the
default install. That being the case, is it okay to keep the name -devel?

Cheers,
Mike


Comment 38 Rahul Sundaram 2008-01-11 11:12:25 UTC
"Default install" is a a fuzzy concept in the bright new world of Fedora spins. 

http://fedoraproject.org/wiki/CustomSpins

If I do a Fedora Documentation Spin, I might very well want to include this
software out of the box as the functionality it brings is much needed in the
documentation team which I am part of. I would suggest that naming not be
dependent on whether it is currently the default in one of the spins we release.

Again, the software is good and we would very much want it to be part of the
Fedora 9 release. We only need to agree on a better naming convention to suit
our guidelines. May I suggest DocsKit?

 


Comment 39 Michael Hideo 2008-01-11 12:20:41 UTC
(In reply to comment #38)
> "Default install" is a a fuzzy concept in the bright new world of Fedora spins. 
> 
> http://fedoraproject.org/wiki/CustomSpins
> 

That's the one! Our target is to create a custom spin for documentation writers,
publishers and syndicators with a series of tools. I am most excited about the
docbot project which is another top level package of -devel. But i need more
time for that one. The command line environment that -devel sets up will suffice
for now.

> If I do a Fedora Documentation Spin, I might very well want to include this
> software out of the box as the functionality it brings is much needed in the
> documentation team which I am part of. I would suggest that naming not be
> dependent on whether it is currently the default in one of the spins we release.
> 
> Again, the software is good and we would very much want it to be part of the
> Fedora 9 release. We only need to agree on a better naming convention to suit
> our guidelines. May I suggest DocsKit?
> 

What I am trying to avoid is a respin of the top level packages that -devel has
created for us in the past. There are 179 top-level projects that reference
-devel in their makefiles for their development. There are 48 owners of these
top level packages we are servicing. Not impossible, but expensive to do. It
will cost about $9k per day and we project a 2 day shutdown for the respin if
everything goes right. But i know something will go wrong, things always do. I
want to minimize risk.

There are a lot of names we could use, I suggest Jeff Fearn's birth-city of
Liverpool to honour his commitment. When we polled the top level package owners,
all hell broke loose and the names kept coming and coming and coming. The
community of use around this -devel package can be very creative and some times
too much creativity can be bad thing.

So Jeff, if you are reading this, will not call it "pants".

- Mike

Comment 40 Michael Hideo 2008-01-11 12:42:23 UTC
(In reply to comment #32)

> Furthermore, I have yet to see a legitimate reason why renaming this package
> would be such a burden beyond the emotional desire to keep it only because it
> was named such internally in the past.

Hi Warren, 

Remember the Library of Alexandria project that I talked about 2 years ago? Well
this is it and you know we're crazy enough to pull it off with the custom spins.
This wombat has a purpose and a direct intention. 

Jim is right, what long term value is Ubuntu generating for open source by their
violation of the law. Power and privledge cannot move a people *if* they stand
in the law.

Whatever it takes, get us on the battlefield!

- Mike

Comment 41 Shankar Prasad 2008-01-11 14:12:48 UTC
As pnemade suggested, I too feel some thing like DocumentationKit suits well for
this. *-devel sounds quite raw to me!

Comment 42 Paul Kennedy 2008-01-11 20:35:34 UTC
Personally, I don't care what it is called as long as it works properly. If we
must rename it to avoid the -devel connotation, then lets keep it simple. For
example "DocKit", if it does not infringe on another product or project name.

Comment 43 Steven J. Levine 2008-01-11 21:21:23 UTC
The name of the package does not affect what I need to do, so the there are no
immediate ramifications to me if the name changes or stays the same. 

Comment 44 Warren Togami 2008-01-11 21:40:44 UTC
Fedora Engineering Steering Committee (FESCo) discussed this during the FUDCon
Friday, Jan 11th 2008 meeting.  FESCo strongly suggests changing the name due to
the *-devel reason.  Additionally, packaging guidelines will soon more
explicitly spell out the rules regarding -devel.

After a name change, it will be fairly easy to get this review done.

There is broad agreement that this needs to be included in Fedora 9.

Will this easily work on Fedora 7 and Fedora 8 as well?
What about RHEL5? (It could be added to EPEL5.)

Comment 45 Murray McAllister 2008-01-12 00:40:56 UTC
To demonstrate how naive and ignorant I am: what would happen if we kept using
the name "documentation-devel" internally, but respun the package with a new
name for Fedora (that would not get used internally)?

- Murray.

Comment 46 Ralf Corsepius 2008-01-12 03:46:20 UTC
(In reply to comment #45)
> To demonstrate how naive and ignorant I am: what would happen if we kept using
> the name "documentation-devel" internally, but respun the package with a new
> name for Fedora (that would not get used internally)?
Your RH-internal business is not of any importance and irrelevant to Fedora.


Comment 47 Michael Hideo 2008-01-12 15:07:35 UTC
(In reply to comment #46)

> Your RH-internal business is not of any importance and irrelevant to Fedora.

I understand. Many apologies to all for the distraction. 

- Mike ่‹ฑ้›„


Comment 48 Warren Togami 2008-01-12 15:23:02 UTC
WAIT!!!

This doesn't mean CANTFIX.  Simply rename the package.  This is important to get
into Fedora 9.

Comment 49 Warren Togami 2008-01-12 15:26:25 UTC
> Your RH-internal business is not of any importance and irrelevant to Fedora.

While this is technically true, this could have been written in a more tactful
and sensitive way.

Comment 50 Parag AN(เคชเคฐเคพเค—) 2008-01-12 15:28:28 UTC
Michael,
Any reason to CLOSE this as CANTFIX? You just need to come up with some good
name that will not contain -devel and simply rename Summary here and submit
package for review.

Comment 51 Michael Hideo 2008-01-14 01:25:40 UTC
(In reply to comment #50)
> Michael,
> Any reason to CLOSE this as CANTFIX? You just need to come up with some good
> name that will not contain -devel and simply rename Summary here and submit
> package for review.

1. Can someone 'own' this bug?
2. Can you put a pointer to the package naming guidelines?

Naming is out in the community, early leads are: 

Endoculator
Documentation-Devil
DocumentationDevel

Although we have the ability to support 4711 packages, we have actually only
compiled 2838 rpms with the devel package. We're going to need more time to get
the show on the road. We should still be good for F9. We'll re-open this bug then.

- Mike

Comment 52 Jens Petersen 2008-01-14 01:43:16 UTC
> 1. Can someone 'own' this bug?

Someone will take the bug when they agree to review the package,
that is the usual procedure.  Anyway don't worry plenty of people
are watching this bug now. :)

> 2. Can you put a pointer to the package naming guidelines?

http://fedoraproject.org/wiki/Packaging/NamingGuidelines

> Naming is out in the community

Cool.

You can continue using this bug for the review (that is
normal procedure for submitted packages that get renamed).


Comment 53 Michael Hideo 2008-01-14 07:33:13 UTC
(In reply to comment #52)
> > 1. Can someone 'own' this bug?
> 
> Someone will take the bug when they agree to review the package,
> that is the usual procedure.  Anyway don't worry plenty of people
> are watching this bug now. :)
> 

10-4

> > 2. Can you put a pointer to the package naming guidelines?
> 
> http://fedoraproject.org/wiki/Packaging/NamingGuidelines
> 

You need to document the implications of the reserve word "-devel" so others do
not make the same mistake I did. This law is not written above. I will stand in
the law so that those with the power and privilege can protect me.

> > Naming is out in the community
> 
> Cool.
> 
> You can continue using this bug for the review (that is
> normal procedure for submitted packages that get renamed).
> 

Will do.


Comment 54 Karsten Wade 2008-01-14 16:15:34 UTC
(In reply to comment #15)  ... some questions and points.

I look forward to finally being able to see this toolchain, and I'm sure many of
us will review it for use or replacement of existing parts of the Fedora Docs
tools/infrastructure.  Major kudos to Jeff, whose work I've long admired and
benefited from.  This package arrives at a good time for tech review as we
revamp parts of documentation production with the help of Fedora Infrastructure.

My comments here have the caveat that I have not done a full feature review of
the toolchain, so I am plainly curious what it provides that is missing in the
existing toolchain and infrastructure.  Especially, what is provided that the
community has been asking for.  If we can answer these questions here, we can
save others from having to do the deep research themselves. :)

> It is a mature project with a significant existing community of users, who have
> it embedded in their enterprise infrastructure.

Is this community entirely internal to Red Hat?  That may explain why no one had
access to the Fedora collective consciousness about *-devel for namespaces,
which is one of those things no one wrote down because, "Everyone knows it." :)

> The package brings together an end-to-end opensource toolchain that
> allows open source projects to produce professional documentation,
> taking several forms of input and outputting html, pdf, manpages,
> xml, and several other formats.
> 
> It produces branded documentation using templates.
>
> It handles multiple language translations.
>
> It's been developed over a number of years and is used in an enterprise setting.
>
> Basically it provides the whole kit and caboodle for professional open source
> documentation production from source. 

Sounds like the existing Fedora Docs Project toolchain.  It does all those
things.  One difference, it was developed by volunteer contributors working from
the Fedora community, so I reckon it hasn't nearly the same amount of features.
 For example, I'm sure it outputs better PDFs since I know Jeff has done a lot
of work at making passivetex and FOP spin and hum.

> In terms of Fedora it provides a missing
> infrastructure piece for documentation production and translations.
>
> In terms of the wider scene it provides a missing infrastructure
> piece, 

Confused here -- we've an existing toolchain that does all this, all built and
hosted within Fedora over many years.  What is missing?

Fedora Infrastructure hasn't come forward yet and said they are missing any of
these functions.  Nor has anyone else from the Fedora community, with the
exception of prettier/unbroken PDFs.

> think that a canonical name is not out of place. Red Hat / Fedora have a history
> of providing significant plumbing pieces to the community (like NetworkManager).

The exception is, those pieces were developed initially in the open, which is
one way to avoid unfortunate namespace problems.

Ironically, we often point to NetworkManager as a lost marketing opportunity,
since common credit for "first use" went to other distributions.  If this doc
toolchain package is going to so significantly change the landscape for free
documentation, we have missed the chance to publicize its development.  Let's
not miss any further opportunities.

Finally, big +1 to the idea of a content development spin.  Huzzah! Let us know
on fedora-docs-list if you want any community contributors and testing.

Comment 55 Joshua Wulf 2008-01-14 19:16:02 UTC
I knew about the *-devel namespace thing, since I've been a Fedora user since
1.92, and I knew that this hurdle would come up. Of course, my opinion didn't
carry much weight because it's an undocumented convention, and they were doing
things by the book.

It's a good point that it isn't written down anywhere. Warren made some nice
technical observations that could serve as a basis for making this into an
explicit policy.

I'd imagine that since this package already has a significant community around
it once it gets included in Fedora we'll find a lot of those people more active
in Fedora. Being "internal" to Red Hat doesn't make you any less of a community
member. I was a Fedora user before I joined Red Hat, and I'll be one after I'm gone.

As far as the name for the package goes, when considering a package name, as
seasoned hands know, the overriding consideration, beyond all technical
concerns, and especially when you're talking community, is "how will it look on
a t-shirt?"

I'd definitely wear a t-shirt with "Endoculator" on it, and someone sent me a
logo proposal for "Documentation-devil", which I'll attach to the bug. I've
already ordered a t-shirt from Cafe Press. Even it doesn't end up as the package
name, it can be a momento of this bug. :-)

Get yours here:
http://www.cafepress.com/cp/customize/product.aspx?clear=true&number=%20213953185

So I'm +1 on Endoculator or documentation-devil for a package name.

Comment 56 Joshua Wulf 2008-01-14 19:16:28 UTC
Created attachment 291615 [details]
proposed documentation-devil logo from teh community

Comment 57 Karsten Wade 2008-01-14 20:08:10 UTC
Lightweight reply while I'm adding myself to the Cc:; ignore if you wish. :)

(In reply to comment #55)
> I knew about the *-devel namespace thing, since I've been a Fedora user since
> 1.92, and I knew that this hurdle would come up. Of course, my opinion didn't
> carry much weight because it's an undocumented convention, and they were doing
> things by the book.
> 
> It's a good point that it isn't written down anywhere. Warren made some nice
> technical observations that could serve as a basis for making this into an
> explicit policy.

We started work on the Fedora Get Involved Guide (GIG) this week:

http://fedoraproject.org/wiki/Docs/Drafts/GetInvolvedGuide

... which is what Paul's (Frields) "Developer Guide" hackfest session turned in
to.  One shakeout from this should be finding similar holes and assumptions in
the packaging process, which comprises a majority of the GIG content.   I'm
certain the missing content about the *-devel convention is going to get fixed
now. :)

> I'd imagine that since this package already has a significant community around
> it once it gets included in Fedora we'll find a lot of those people more active
> in Fedora. Being "internal" to Red Hat doesn't make you any less of a community
> member. I was a Fedora user before I joined Red Hat, and I'll be one after I'm
gone.

Agreed; I didn't meant to imply anything else or to assign different values to
different communities.  It was an observation that explained the disconnection
up to this point.

> As far as the name for the package goes, when considering a package name, as
> seasoned hands know, the overriding consideration, beyond all technical
> concerns, and especially when you're talking community, is "how will it look on
> a t-shirt?"

Darn tootin'! 


Comment 58 Jeff Fearn ๐Ÿž 2008-01-14 21:12:47 UTC
(In reply to comment #44)
> Will this easily work on Fedora 7 and Fedora 8 as well?
> What about RHEL5? (It could be added to EPEL5.)

We currently have this building in brew for RHEL 4 & 5.

Some people who use Fedora hook up to our noarch repo for RHEL5 and run those
packages on Fedora 7, 8 and Raw Hide. No issues have been reported by those users.


Comment 59 Michael Hideo 2008-01-14 21:56:59 UTC
(In reply to comment #56)
> Created an attachment (id=291615) [edit]
> proposed documentation-devil logo from teh community
> 

lol, you JBoss guys crack me up!

Comment 60 Brian Forte 2008-01-15 00:02:54 UTC
A Printer's Devil was an assistant or apprentice to a Printer. They mixed inks, fetched supplies, re-filled type 
trays, carried paper and generally did all the scut work the Printer didn't want to do anymore.

The term's origins are uncertain with the assistants to William Caxton (who was named Deville) and Aldus 
Manutius (who was a Moor) both being credited by different sources.

OTOH, printing was also seen as akin to the Black Arts in its early days in Europe (not surprising given the 
Church's desire to remain the sole source of Truth). Throw in the tendency of printers and apprentice 
printers to get covered in black ink and the idea they might be devils wasn't a massive leap to mediaeval 
folk, raised to believe black = bad.

Consequently, the Printer's Devil was sometimes something other than a put-upon worker. It has also 
referred to an imp which supposedly came out at night and indulged in mischief, re-arranging type trays, 
moving letters around on already set type and so on.

Both these uses make documentation-devil (or 'Docs devil', to use what I suspect would quickly become the 
use-name) almost perfect as a package name. Docs devil is an assistant to a writer, doing scut work we 
don't want to do (and shouldn't have to do) and it's a convenient scapegoat for those magic typos that only 
appear after the book has gone public.

That this name also preserves, forever, the argument that erupted about the package's name adds 
appropriate Linux-specific lore. This lore is eminently suitable for adding colour and interest to the 
introductory chapters of future books documenting Docs devil.

Comment 61 Lana Brindley 2008-01-15 00:52:15 UTC
> That this name also preserves, forever, the argument that erupted about the
package's name adds 
> appropriate Linux-specific lore. This lore is eminently suitable for adding
colour and interest to the 
> introductory chapters of future books documenting Docs devil.

... and will form a suitable wikipedia entry in years to come ;)

Comment 62 Christopher Curran 2008-01-15 01:04:33 UTC
+1 to Loremaster Brian's input. 

As for any opposition to devil being in the title there are already plenty of
open source projects with the word devil in the title. A quick goole will reveal
that or just check this link,
http://sourceforge.net/search/?type_of_search=soft&type_of_search=soft&words=devil
The horse on that issue has long bolted from the gate.

I've got no issues with the name. We could even append Brain Forte's brief
history of printing in Europe to the man for the package.

Can someone just take ownership of this bug so it can get in fedora?


Christoph

Comment 63 Joshua Wulf 2008-01-15 01:04:37 UTC
Created attachment 291662 [details]
One does not simply "name a package in Fedora", just as...

Comment 64 Andy Fitzsimon 2008-01-15 01:11:44 UTC
one does not simply rock into mordor!
http://farm1.static.flickr.com/43/87366880_1b05bf99e2.jpg


Comment 65 Andy Fitzsimon 2008-01-15 01:18:29 UTC
Created attachment 291664 [details]
project image

endoculator are belong to us

Comment 66 Christopher Curran 2008-01-15 01:41:42 UTC
Created attachment 291667 [details]
sparta

Just to carry on with the humourous vein of previous posts.

Comment 67 Jens Petersen 2008-01-15 02:31:21 UTC
(In reply to comment #62)
> Can someone just take ownership of this bug so it can get in fedora?

Please see comment 52.  I think the review is currently waiting the submission
of an updated package.


Good to see all the openness about the new name.
I am not going to express any opinions - though I would recommend
something reasonably short and maybe without a hyphen since that would give
a stronger identity to the project I believe.

Comment 68 Jeff Fearn ๐Ÿž 2008-01-15 02:39:28 UTC
(In reply to comment #67)
> (In reply to comment #62)
> > Can someone just take ownership of this bug so it can get in fedora?
> 
> Please see comment 52.  I think the review is currently waiting the submission
> of an updated package.

Can people please be patient, getting approval to tool around with your
production environment takes time.

> Good to see all the openness about the new name.
> I am not going to express any opinions - though I would recommend
> something reasonably short and maybe without a hyphen since that would give
> a stronger identity to the project I believe.

I told them Pants was a damn fine name.

Comment 69 Jeff Fearn ๐Ÿž 2008-01-16 04:37:44 UTC
I note that although a few people have commented on this name being
unacceptable, none of those people felt strongly enough to actually update the
wiki with the new rules. Updated rules would have been nice to have before
considering new names.
Rrepackage everything before considering a new name is onerous and could quickly
become a very annoying experience.

Having said that, here are links to the new spec file and srpm.

http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devil.spec
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devil-0.26-3.fc9.src.rpm

Comment 70 Jeff Fearn ๐Ÿž 2008-01-16 04:39:01 UTC
(In reply to comment #69)
> Rrepackage everything before considering a new name is onerous and could quickly

Repackaging ... shut up! ;)

Comment 71 Parag AN(เคชเคฐเคพเค—) 2008-01-16 04:53:09 UTC
(In reply to comment #69)
> I note that although a few people have commented on this name being
> unacceptable, none of those people felt strongly enough to actually update the
> wiki with the new rules. Updated rules would have been nice to have before
> considering new names.
   Those packaging guidelines wiki pages have ACLs set on them. I think only
Fedora Packaging Committee members can commit there.

Comment 72 Michael Hideo 2008-01-16 05:03:07 UTC
(In reply to comment #69)
> I note that although a few people have commented on this name being
> unacceptable, none of those people felt strongly enough to actually update the
> wiki with the new rules. Updated rules would have been nice to have before
> considering new names.
> Rrepackage everything before considering a new name is onerous and could quickly
> become a very annoying experience.
> 
> Having said that, here are links to the new spec file and srpm.
> 
>
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devil.spec
>
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devil-0.26-3.fc9.src.rpm

Jeff,

I see that 15th century literature won out over the 21st century!
http://en.wikipedia.org/wiki/William_Caxton

Andy, when you get a spare cycle can you give us a cool logo, kind of like the
devil from:   http://www.openi18n.org/ would be great.

The first book to land into fedora should be the Internationalization Guide. W/o
i18n, we wouldn't be here!

Cheers,
Mike







Comment 73 Jens Petersen 2008-01-16 07:47:35 UTC
Thanks for the update. :)  Taking this review.

Commenting below on
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devil.spec
since spec file in srpm appears to be slightly older.

Just a few comments for upstream on the tarball:
- Are all "Common_Content/common/*/images/*.png" the same?  It would save quite
a bit of space sharing the images (just a comment though).
- It would be nice to preserve timestamps when generating the tarball if possible.
- Upstream's docbook-xsl-1.72.0/doc/ is empty.
- The latest upstream docbook-xsl is 1.73.2 any plans to update to it at some
point?  (docbook-style-xsl-1.73.2 is already in fedora)
- There is po2xliff in translate-toolkit: dunno how it compares with po2xlf

(these are not blockers - just things to consider upstream)

Comment 74 Jens Petersen 2008-01-16 08:00:58 UTC
Created attachment 291829 [details]
documentation-devil.spec-1.patch

Some proposed cleanup.

Mostly the package looks ok to me.

Comment 75 Jeff Fearn ๐Ÿž 2008-01-17 04:27:45 UTC
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devil.spec
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/documentation-devil-0.26-4.fc9.src.rpm

* Thu Jan 17 2008 Jeff Fearn <jfearn> 0.26-4
- Tidy up %%files, %%build, %%prep and remove comments from spec file.
- Added --atime-preserve to tar command


Comment 76 Jens Petersen 2008-01-18 01:52:42 UTC
One more comment about the docbook files:
I realised fedora's docbook-dtds provides docbook/dtd-4.5/ so
it would be better to use that than ship your own.

Comment 77 Jens Petersen 2008-01-21 05:56:56 UTC
As an experiment I tried the following:

$ rpm -q docbook-style-xsl
docbook-style-xsl-1.73.2-4.fc8.noarch
$ rm -rf documentation-devil-0.26
$ tar zxf documentation-devil-0.26.tgz
$ cd documentation-devil-0.26
$ rm -r xsl/docbook
$ sed -i -e
"s%http://docbook.sourceforge.net/release/xsl/1.72.0%http://docbook.sourceforge.net/release/xsl/1.73.2%"
xsl/*.xsl
$ make docs

and it seems to build ok.

So unless there are any known issues with docbook-xsl-1.73.2
I think it would be safe not to include "xsl/docbook/".
It would also reduce the installed size from 34MB to 14MB
and reduce the binary package from 7MB to 3MB.

Would it be possible upstream to change the license to be explicitly GPL2?
It would be good if there were explicit license headers in the source files.

In fop/ are both font-metrics/ and font-metrics-0.93/ needed?
In a way it would be nice if the font metric data could be generated
at build time but maybe that could be done later.

It might be better to move the desktop file to a separate file at some point
specially if it is going to be translated, or just to include it in the source?

Comment 78 Jens Petersen 2008-01-21 06:02:29 UTC
Created attachment 292331 [details]
documentation-devil.spec-xsl.patch

Just for reference this is what I used to test the above.

(If "docbook/" goes then it would be good to update "make/Makefile.templates"
not to set CATALOGS to point there anymore.)

Comment 79 Jens Petersen 2008-01-22 06:28:44 UTC
(I guess I don't know enough about xml but the above patch increases the
build time from about 30s to about 14min - presumably it is causing
it to make network connections, timeouts or such like.)

Comment 80 Benjamin Kosnik 2008-01-24 15:48:03 UTC
Here are some issues that I think should be addressed before this package is
pushed out into Fedora:

1) duplication of xsl stylsheets between

docbook-style-xsl-1.73.2-4.fc8
documentation-devel-0.26-1.fc8

Specific files and directories:
/usr/share/documentation-devel/xsl/docbook/1.72.0/*

Instead, documentation-devel should depend on docbook-style-xsl and reference
those stylesheets.

2) The Red Hat and Red Hat product parts of the Makefile.common should be
removed. These belong in the Red Hat specific packages, not in a general thing. 

IE:

/usr/share/documentation-devel/make/Makefile.common:

%grep Red Makefile.*
Makefile.common:#Makefile for Red Hat Documentation
Makefile.common:#Copyright Red Hat Inc. 2006
Makefile.common:ifeq "$(PRODUCT)" "Red_Hat_Enterprise_Linux"

3) invalid XHTML for "html" make target. There is already a bug report about this:
https://bugzilla.redhat.com/show_bug.cgi?id=428931

"By hand" docbook with the current FC8 toolchain validates as XHTML 1.0, so this
should too.

Comment 81 Jeff Fearn ๐Ÿž 2008-01-31 07:28:26 UTC
I am thinking of renaming this package "publican" would anyone have a problem
with this?

Comment 82 Jens Petersen 2008-02-04 00:05:51 UTC
Sounds fine to me.

Comment 83 Jeff Fearn ๐Ÿž 2008-02-07 06:05:17 UTC
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/publican-0.27-0.fc9.src.rpm
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/publican.spec

* Thu Feb 07 2008 Jeff Fearn <jfearn> 0.27-0
- Use docbook-style-xsl
- Update custom xsl to use docbook-xsl-1.73.2
- Remove CATALOGS override
- Remove Red Hat specific clause from Makefile.common
- Fixed inavlid xhtml BZ 428931
- Update License to GPL2
- Add GPL2 Header to numerous files
- renamed from documentation-devil to publican

Bumped the version due to code changes.

I'm pretty sure I didn't miss anything :)

Comment 84 manuel wolfshant 2008-02-07 10:12:46 UTC
Source RPM: publican.src: W: invalid-license GPL2
In the source I see that GPLv2+ (all the /bin/*), GPL and GFDL are all
mentioned. In the same line, since you are upstream, could you please include
the license file(s) in the source ?

Desktop file: vendor should be fedora. Also, I think it is not really nice to
dynamically create the desktop file, but that may be just me too picky.

There is no downloadable source. Any chance of having a full URL in the Source tag ?


Comment 85 Jens Petersen 2008-02-07 14:53:24 UTC
Thanks for the updated package, Jeff.

Yes, thanks Manuel, the license points and source url certainly need to be
addressed.

Some more remarks:

The documentation under %_docdir is about 1.2MB in size, so I think it must
be moved to a separate subpackage, say publican-docs, along with the desktop
file.

Also BTW in F9 the default desktop font is changing from dejavu-lgc-fonts to
dejavu-fonts (a superset of dejuvu-lgc-fonts with wider language coverage).

It would probably be good to tag /usr/share/publican/Common_Content/common/*-*
with %lang tags too.

(Now that the new project name has been settled, I think it would be worth
renaming the project on fedorahosted.org to publican too to be consistent.)


Comment 86 Jens Petersen 2008-02-07 15:26:29 UTC
(In reply to comment #85)
> The documentation under %_docdir is about 1.2MB in size, so I think it must
> be moved to a separate subpackage, say publican-docs, along with the desktop
> file.

Sorry doc subpackage should be named publican-doc (according to
http://fedoraproject.org/wiki/Packaging/NamingGuidelines).

Comment 87 Jens Petersen 2008-02-07 15:53:39 UTC
Here is the formal review (following
http://fedoraproject.org/wiki/Packaging/ReviewGuidelines):

 +: good, -: needs fixing, =: needs attention

MUST Items:
[+] MUST: rpmlint must be run on every package.

publican.noarch: E: explicit-lib-dependency libxslt  [ok]
publican.noarch: W: invalid-license GPL2  [Needs fixing - see above]
publican.noarch: W: obsolete-not-provided documentation-devel  [ok]

[+] MUST: The package must be named according to the Package Naming Guidelines.
[+] MUST: The spec file name must match the base package %{name}, in the format
%{name}.spec
[+] MUST: The package must meet the Packaging Guidelines.

[=] MUST: The package must be licensed with a Fedora approved license and meet
the Licensing Guidelines.
[=] MUST: The License field in the package spec file must match the actual license.
[=] MUST: If (and only if) the source package includes the text of the
license(s) in its own file, then that file, containing the text of the
license(s) for the package must be included in %doc.

See comments above: main package and -doc subpackage should mention the license
of the documentation and templates.

[+] MUST: The spec file must be written in American English.
[+] MUST: The spec file for the package MUST be legible.
[-] MUST: The sources used to build the package must match the upstream source,
as provided in the spec URL. Reviewers should use md5sum for this task. If no
upstream URL can be specified for this package, please see the Source URL
Guidelines for how to deal with this.

As commented earlier.

[+] MUST: The package must successfully compile and build into binary rpms on at
least one supported architecture.
[+] MUST: All build dependencies must be listed in BuildRequires
[+] MUST: The spec file MUST handle locales properly. This is done by using the
%find_lang macro.

See suggestion above though.

[+] MUST: A package must own all directories that it creates.
[+] MUST: A package must not contain any duplicate files in the %files listing.
[+] MUST: Permissions on files must be set properly.
[+] MUST: Each package must have a %clean section
[+] MUST: Each package must consistently use macros
[+] MUST: The package must contain code, or permissable content.

[-] MUST: Large documentation files should go in a -doc subpackage. (The
definition of large is left up to the packager's best judgement, but is not
restricted to size. Large can refer to either size or quantity)

See above posted comment.

[+] MUST: If a package includes something as %doc, it must not affect the
runtime of the application.
[-] MUST: Packages containing GUI applications must include a %{name}.desktop
file, and that file must be properly installed with desktop-file-install in the
%install section. This is described in detail in the desktop files section of
Packaging Guidelines. If you feel that your packaged GUI application does not
need a .desktop file, you must put a comment in the spec file with your explanation.

Must use desktop-file-install

[+] MUST: Packages must not own files or directories already owned by other
packages.
[+] MUST: At the beginning of %install, each package MUST run rm -rf
%{buildroot} (or $RPM_BUILD_ROOT).
[+] MUST: All filenames in rpm packages must be valid UTF-8.

SHOULD Items:
[=] SHOULD: If the source package does not include license text(s) as a separate
file from upstream, the packager SHOULD query upstream to include it.
[+] SHOULD: The reviewer should test that the package builds in mock. See
MockTricks for details on how to do this.


Comment 89 Jens Petersen 2008-02-07 16:11:52 UTC
Created attachment 294222 [details]
publican.spec-1.patch

See http://fedoraproject.org/wiki/Packaging/Guidelines for
BuildRoot and using desktop-file-install.

Comment 90 Karsten Wade 2008-02-07 17:23:15 UTC
Curious as to why the GFDL is being used for the -docs?  Of course, this is not
a Fedora document, and the license choice is at the discretion of the upstream.
 But if you ever wanted Fedora to publish the how-to documentation included in
this package, it needs to be under the OPL without restrictions.  If you want to
leave that concern for the future, Red Hat (as the copyright holder) can always
relicense or dual license.  But since you are addressing the licensing in the
-brand packages, thought you might want to handle this one at the same time.

Comment 91 Jeff Fearn ๐Ÿž 2008-02-08 01:03:38 UTC
(In reply to comment #90)
> Curious as to why the GFDL is being used for the -docs?  Of course, this is not
> a Fedora document, and the license choice is at the discretion of the upstream.
>  But if you ever wanted Fedora to publish the how-to documentation included in
> this package, it needs to be under the OPL without restrictions.  If you want to
> leave that concern for the future, Red Hat (as the copyright holder) can always
> relicense or dual license.  But since you are addressing the licensing in the
> -brand packages, thought you might want to handle this one at the same time.

The default license, GFDL, was chosen because the brand packages each use a
different free(ish) license and I thought adding one more free license to the
mix couldn't hurt :)

My method was to pick one of the "Good Licenses" from
http://fedoraproject.org/wiki/Licensing#head-19fc3ef10add085a28cb06784dc34ef8b05a9bd6-2
 that wasn't covered by any of the brand packages.

The docs in this package use the default brand & license, thus they get the GFDL.

I'd like to change the default license to Creative Commons Share-Alike (CC-SA)
v3.0 as it's the only documentation license I could find that is accepted as
free by Debian, and so would enable the widest distribution of this package. See
http://wiki.debian.org/DFSGLicenses


Comment 92 Jens Petersen 2008-02-08 04:35:12 UTC
(In reply to comment #85)
> It would probably be good to tag /usr/share/publican/Common_Content/common/*-*
> with %lang tags too.

(Thinking more, I am not really sure if this is a good idea or makes sense:
anyway probably not worth doing at this state anyhow.)

Comment 93 Jeff Fearn ๐Ÿž 2008-02-11 07:29:51 UTC
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/publican-0.28-0.fc9.src.rpm
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/publican.spec

Had to bump the version as I had a couple of important bugs to fix :(

* Mon Feb 11 2008 Jeff Fearn <jfearn> 0.28-0
- Added gpl.txt
- Fix GPL identifier as GPLv2+
- Fixed Build root
- Fix desktop file
- Added Provides for documentation-devel
- Fix dist build target
- Add dist-srpm target
- fix dist failing on missing pot dir
- Put docs in sub package
- Added GFDL to License to cover content and Book_Template directories.
- Included GFDL txt file
- set full path to source


Comment 94 Karsten Wade 2008-02-11 13:37:15 UTC
(In reply to comment #93)
> 
> - Added GFDL to License to cover content and Book_Template directories.
> - Included GFDL txt file

I want to reiterate a point here because it may save time and hassle in the
future if we resolve this now.

You may recall that when the Fedora Project was formed, all the Docs Project
work was under the GFDL.  This was done as an assumptive move by Project
founders, they never asked Legal what license to use, and it turned out to be a
mistake.  Red Hat Legal (Mark Webbink) required us to re-license all the
content, which was a fair bit of work.

It is not clear to me if the upstream of publican (in the form of Red Hat's
Content Services team) is actually permitted to use the GFDL.  It sounds as if
you chose to pick a good license from the Fedora Project list and Red Hat Legal
may not have been involved in the license choice?

Based on the previous commit, it sounds as if Book_Template is covered by the
GFDL.  I can see in the Book_Info.xml file that Common_Content/Legal_Notice.xml
is called by the template.

https://fedorahosted.org/documentation-devel/browser/trunk/publican/Book_Template/en-US/Book_Info.xml

Does that make just the template under the GFDL or ...?  If the template is
under the GFDL, I'm unclear on how Fedora is going to use the tool.  If I use it
to make a book for Fedora, but the book *cannot* be under the GFDL due to
Legal's previous restrictions, how does the license affect the content I am
going to write into that template?  If it makes the content GFDL, then that
template cannot be used for Fedora content.

This is why I have been advocating across the board usage of the OPL without
restrictions for all parts of publican, from the tools to the templates to the
branding files.  True, there are other licenses that a package can use and have
that package be in Fedora (the distro).  But if you want the package to be
useful to Fedora (the Project), this mix of licenses does not make it clear that
it *can* be used.


Comment 95 Jeff Fearn ๐Ÿž 2008-02-11 23:50:28 UTC
(In reply to comment #94)
> (In reply to comment #93)
> > 
> > - Added GFDL to License to cover content and Book_Template directories.
> > - Included GFDL txt file
> 
> I want to reiterate a point here because it may save time and hassle in the
> future if we resolve this now.
> 
> You may recall that when the Fedora Project was formed,

lol Sometimes I think you forget just how long you have been around! I certainly
haven't been around that long :D

> all the Docs Project
> work was under the GFDL.  This was done as an assumptive move by Project
> founders, they never asked Legal what license to use, and it turned out to be a
> mistake.  Red Hat Legal (Mark Webbink) required us to re-license all the
> content, which was a fair bit of work.
> 
> It is not clear to me if the upstream of publican (in the form of Red Hat's
> Content Services team) is actually permitted to use the GFDL.  It sounds as if
> you chose to pick a good license from the Fedora Project list and Red Hat Legal
> may not have been involved in the license choice?

The default template is not used by the Red hat Documentation Team, they use a
different brand licensed under the OPL + Restrictions.

The default brand is intended for use by the general open source community and
not Red hat or Fedora specific documentation.

> Based on the previous commit, it sounds as if Book_Template is covered by the
> GFDL.  I can see in the Book_Info.xml file that Common_Content/Legal_Notice.xml
> is called by the template.

Ahhh! Nicely spotted! I should have split out the Book_Template in to each of
the brands when I split out the other common content. I will put up new packages
today with the per brand Book_Templates.

>
https://fedorahosted.org/documentation-devel/browser/trunk/publican/Book_Template/en-US/Book_Info.xml
> 
> Does that make just the template under the GFDL or ...?  If the template is
> under the GFDL, I'm unclear on how Fedora is going to use the tool.  If I use it
> to make a book for Fedora, but the book *cannot* be under the GFDL due to
> Legal's previous restrictions, how does the license affect the content I am
> going to write into that template?  If it makes the content GFDL, then that
> template cannot be used for Fedora content.
> 
> This is why I have been advocating across the board usage of the OPL without
> restrictions for all parts of publican, from the tools to the templates to the
> branding files.  True, there are other licenses that a package can use and have
> that package be in Fedora (the distro).  But if you want the package to be
> useful to Fedora (the Project), this mix of licenses does not make it clear that
> it *can* be used.

publican-fedora is licensed under the OPL, no restrictions, any content that is
being used from the main package will be duplicated in to the fedora specific
brand package. I think I have it all duplicated now, but i will take another
look over it to check again.

Thanks for looking over this package and highlighting things I missed splitting
out .. maybe there is something to this "many eyes" philosophy :)



Comment 96 Jens Petersen 2008-02-12 04:35:37 UTC
Thanks for the update.

> - Added gpl.txt

Thanks.  This is usually called "COPYING".
However the file you included is GPLv3.

> - Fix desktop file

Thanks.

> - Added Provides for documentation-devel

publican.src:20: W: unversioned-explicit-provides documentation-devel

I would suggest just to drop it unless there is a good
reason to keep it, in which case it should be versioned (see
Packaging/NamingGuidelines).

> - Put docs in sub package

Thanks!

> - Included GFDL txt file

fdl.txt is missing from the tarball.
Please also include it in the doc subpackage.

> - set full path to source

The url needs to go in the Source field.  The URL field is for the project URL.


Comment 97 Jens Petersen 2008-02-12 04:41:01 UTC
> Please also include [fdl.txt] in the doc subpackage.

Or what is the license of the docs?



Comment 98 Jens Petersen 2008-02-12 04:43:40 UTC
Created attachment 294625 [details]
publican.spec-2.patch

some more cleanup suggestions

Comment 99 Jeff Fearn ๐Ÿž 2008-02-12 05:48:20 UTC
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/publican-0.29-0.fc9.src.rpm
http://svn.fedorahosted.org/svn/documentation-devel/trunk/Files/publican.spec

* Tue Feb 12 2008 Jeff Fearn <jfearn> 0.29-0
- Setup per Brand Book_Templates
- Fix soure and URL paths
- Use release in source path
- correct GPL version text and changed file name to COPYING
- dropped Provides
- reordered spec file
- added fdl.txt to tar ball.
- added fdl.txt to doc package


Comment 100 Jens Petersen 2008-02-12 06:47:06 UTC
Thanks

> - Use release in source path

I don't really like this.  If you want to use subminor versioning that is fine.
You can version how you like upstream, but moving the "release" number there
just makes things more complicated for fedora and other distros when packaging.

> - added fdl.txt to tar ball.
> - added fdl.txt to doc package

It would be better to upcase the filename, IMHO.
How about just using COPYING.FDL?


Comment 101 Jens Petersen 2008-02-12 06:49:29 UTC
Created attachment 294631 [details]
publican.spec-3.patch

Please use the desktop scriptslets from
http://fedoraproject.org/wiki/Packaging/ScriptletSnippets#head-de6770dd9867fcd085a73a4700f6bcd0d10294ef


Otherwise I think the package looks ok now.

Comment 102 Mamoru TASAKA 2008-02-12 07:45:41 UTC
Well, I have not read the whole comments of this bug yet, but:

--------------------------------------------------------------------------
sed -i -e 's|@@FILE@@|%{_docdir}/%{name}-%{version}/en-US/index.html|'
%{name}.desktop
sed -i -e 's|@@ICON@@|%{_docdir}/%{name}-%{version}/en-US/images/icon.svg|'
%{name}.desktop
--------------------------------------------------------------------------
What html and svg files this sed command points to? %{name} is expanded to
"publican", not "publican-doc". As far as I checked the rebuild rpms,
the files under %_docdir/%name-%version are onlhy 3 files,
COPYING, README, fdl.txt.

Comment 103 Mamoru TASAKA 2008-02-12 07:48:08 UTC
Also:

[Desktop Entry]
Name=Publican
Comment=How to use Publican
Exec=htmlview /usr/share/doc/publican-0.29/en-US/index.html

Requires: htmlview should be added to -doc subpackage? (by the
way this should be replaced by xdg-open?)

Comment 104 Jeff Fearn ๐Ÿž 2008-02-12 23:09:35 UTC
I got great service from the Fedora infrastructure team, so there are new urls
for this project. Sorry if this blocked anyone from checking things out.

http://svn.fedorahosted.org/svn/publican/trunk/Files/publican-0.29-1.fc9.src.rpm
http://svn.fedorahosted.org/svn/publican/trunk/Files/publican.spec

- removed %%post and %%postun as update-desktop-database is for desktop files
with mime types
- removed release for source path and tar name
- fixed package name in desktop file to include -doc
- switched from htmlview to xdg-open
- Added xdg-utils requires for doc package


Comment 105 Jens Petersen 2008-02-13 00:52:34 UTC
Thanks for the update, Jeff.

For the record here is the rpmlint output now:

 publican.src: W: mixed-use-of-spaces-and-tabs (spaces: line 86, tab: line 1)

which you may want to fix before importing to cvs, and:

 publican.noarch: E: explicit-lib-dependency libxslt
 publican.noarch: W: obsolete-not-provided documentation-devel

which are ok.

(BTW I filed a bug to have po2xml moved from kdesdk to a separate subpackage
to avoid the huge dependency on kdesdk.)

Updating the remaining MUST items from the review in comment 87:

[+] MUST: The package must be licensed with a Fedora approved license and meet
the Licensing Guidelines.
[+] MUST: The License field in the package spec file must match the actual license.
[+] MUST: If (and only if) the source package includes the text of the
license(s) in its own file, then that file, containing the text of the
license(s) for the package must be included in %doc.

[+] MUST: The sources used to build the package must match the upstream source

8e3b3709c1daad154be9759a6c8ee443  publican-0.29.tgz

[+] MUST: Large documentation files should go in a -doc subpackage.
[+] MUST: Packages containing GUI applications must include a %{name}.desktop
file, and that file must be properly installed with desktop-file-install in the
%install section.

So AFAICT all review MUST items are now satisfied, and all the major points
raised have been addressed I think.  I am not a license lawyer obviously,
but the licensing seems reasonable enough to me - if there should
still be issues with the interactions of the licenses I hope they can be
ironed out later if necessary.

Thanks for the review.

Package is APPROVED for inclusion in Fedora.

Comment 106 Jeff Fearn ๐Ÿž 2008-02-13 02:26:30 UTC
New Package CVS Request
=======================
Package Name: publican
Short Description: publication tool chain
Owners: jfearn
Branches: devel F-8 EL-4 EL-5
InitialCC: mdious
Cvsextras Commits: yes

Comment 107 Jens Petersen 2008-02-13 02:39:30 UTC
cvs admin done

Comment 108 Jens Petersen 2008-02-13 07:17:06 UTC
Jeff imported and build the package for development.

Comment 111 Karsten Wade 2008-02-13 19:33:41 UTC
We're not likely to make a release note about this.

OTOH, we could talk about making it a feature of Fedora 9, which includes
release note information; if we pursue that, we'll track the notes through the
feature process:

http://fedoraproject.org/wiki/Features/Policy

Let's talk about this idea via fedora-docs-list, after we've knocked things
around a bit.

Comment 112 John Poelstra 2008-02-13 19:50:40 UTC
Do things that are only on the media version of the release get release notes?

Yes, a feature page would definitely draw more visibility to this new package.

Comment 113 Karsten Wade 2008-02-13 20:33:13 UTC
(In reply to comment #112)
> Do things that are only on the media version of the release get release notes?

Not necessarily.  In the past, we gave priority to what was in the main media
version.  Not sure now where that line is.

In general, we've avoided putting much energy into reporting on every new and
interesting package.

> Yes, a feature page would definitely draw more visibility to this new package.

I'll rescind my comment that it is not release note worthy; obviously if it's a
good feature, it's worthy.  I more meant that we don't really have a place
(beat) in the notes to cover this area other than "New Feature."  We could,
though, esp. if we decide to do some kind of Documenter/Publisher Spin.


Comment 114 Jens Petersen 2008-02-13 23:50:36 UTC
> Not necessarily.  In the past, we gave priority to what was in the main media
> version.

Good point.

> I more meant that we don't really have a place
> (beat) in the notes to cover this area other than "New Feature". 

Yeah might be nice to have Docs docsbeat at some point anyway. :)

(Anyway this conversation should probably move elsewhere... :)

Comment 115 Ruediger Landmann 2013-06-07 00:37:59 UTC
Package Change Request
======================
Package Name: publican
New Branches: el6-docs
Owners: rlandmann

Comment 116 Gwyn Ciesla 2013-06-07 12:44:28 UTC
EL-6-docs


Note You need to log in before you can comment on or make changes to this bug.