Description of problem: Publican documentation packages all install into the one directory: <webroot>/docs. This means that only one documentation site can be served from a machine. If the doc root were configurable, a server could host multiple documentation sites; for example, for different product lines. This would significantly improve navigation on large documentation sites. Version-Release number of selected component (if applicable): 2.5 How reproducible: 100% Steps to Reproduce: 1. Build a web SRPM 2. Inspect spec file Actual results: Note: %define wwwdir %{_localstatedir}/www/html/docs and cp -rf publish/en-US $RPM_BUILD_ROOT/%{wwwdir}/. Expected results: Make wwwdir configurable in the config file Additional info: We'd also need to be able to generate separate databases for different sites
The problem with this is that it requires knowledge of the web site structure by the author before books can be built. The correct solution would involve building relocatable packages, http://www.rpm.org/max-rpm/s1-rpm-reloc-building-relocatable.html Not sure this will be in Publican 3.0
In the particular use case that led us to this we would know the location. The scenario is that for an up-coming release it has been requested that we not only deploy docs to docs.redhat.com but also along with the application. It is envisaged this will allow the html documentation to be used in providing context sensitive help. The application in question runs on JBoss, as such they have a directory under the JBoss installation which is effectively their wwwroot and that is where they wish to deploy the docs. This location is understood to be fixed but obviously is different from the /var/www/html/docs directory into which the docs web RPMs deploy currently.
Ah I see, application specific sites are doable, although we may have to tweak package names and the like.
It occurs to me that the biggest question here is what OS is this intended for? If the target is RHEL 4/5 then we need to be able to add the entire Publican stack in to a brew root for those OS's. If the target is RHEL 6 then we will need to be able to update the version of Publican in RHEL 6, or add the entire Publican stack in to another brew root where we can ship an updated Publican. The reason for this is that the web site packages require Publican on the system they are being installed on to. Perhaps a better option would be to allow the desktop packages to switch formats. e.g. instead of it containing html-desktop it could contain the eclipse output, or HTML chunked, instead. Since the desktop packages created in docs-5E do not require publican on the end users system, this would alleviate the need to get an updated Publican shipped.
Currently builds are occurring on RHEL5 due to delays in another dependency being ready for RHEL6 but the ultimate target is RHEL6. We are aware of the brew root requirements to be able to distribute the web packages and PM have been made aware of this as well. Ultimately however I'm a big fan of the path of least resistance... As you've probably guessed the reason the web packages were chosen is primarily that they provide the chunked html output which is more conducive to context sensitive help than the html-single output format. If as you suggest we could allow switching of formats that are built in the desktop packages then this would I believe fulfill our needs. As noted we would still need to either create or update a RHEL 6 brew root with the updated version of publican in it to build these packages but this would alleviate the need to get it shipped to customers.
I'm thinking that this level of customisation really requires the team concerned to manage their own packaging. Automating arbitrary rules in an upstream system is asking for headaches. e.g. there is nothing stopping any package from using publican to build their docs, in any format, and then just stuffing them wherever they see fit. BuildRequires: publican publican-BRAND %build cd MYBOOK && publican build --etc --etc %install cp -rf MYBOOK/tmp/en-US/html $BUILD_ROOT/a/ver/log/path/. %files /a/ver/log/path/html Firther thought required!
Added 3 new parameters that can be set in brands to control the configuration of web site packages. web_dir: The full path to where files will be installed. web_cfg: The full path to the Publican site config file. web_req: The name of the RPM package that will supply the Publican site config file. The rationale behind limiting these fields to brands is that this is a system level task and should not be controlled at the book level. Committed revision 1763.
(In reply to comment #7) > Added 3 new parameters that can be set in brands to control the configuration > of web site packages. > > web_dir: The full path to where files will be installed. > > web_cfg: The full path to the Publican site config file. > > web_req: The name of the RPM package that will supply the Publican site config > file. > > > The rationale behind limiting these fields to brands is that this is a system > level task and should not be controlled at the book level. > > Committed revision 1763. So to QE verify this, the tester would need to: 1. Make a custom brand according to [1]. 2. Set the parameters above according to the guidance provided. 3. Build a publican site and test the functionality. [1] - http://jfearn.fedorapeople.org/en-US/Publican/2.7/html-single/Users_Guide/index.html#sect-Users_Guide-Files_in_the_brand_directory I've also observed that the parameters mentioned are not present in any staged version of the Publican User Guide. These probably need to be documented as part of this issue, before being marked as VERIFIED?
(In reply to comment #8) > I've also observed that the parameters mentioned are not present in any staged > version of the Publican User Guide. These probably need to be documented as > part of this issue, before being marked as VERIFIED? Oh we don't have a process for updating the PUG from RFE's ... How about we make one? My suggestion: 1: Create a BZ for updating the PUG for version X.Y. 2: When an RFE bug gets verified we change the status to verified and link the RFE bug to the PUG update bug. 3: We assign the PUG update bug to Rudi :D Step 2 could be a 'See Also' or a 'Blocks', as long as the person doing the PUG update knows they need to document something.
(In reply to comment #9) > (In reply to comment #8) > > I've also observed that the parameters mentioned are not present in any staged > > version of the Publican User Guide. These probably need to be documented as > > part of this issue, before being marked as VERIFIED? > > Oh we don't have a process for updating the PUG from RFE's ... How about we > make one? > > My suggestion: > > 1: Create a BZ for updating the PUG for version X.Y. > 2: When an RFE bug gets verified we change the status to verified and link the > RFE bug to the PUG update bug. > 3: We assign the PUG update bug to Rudi :D > > Step 2 could be a 'See Also' or a 'Blocks', as long as the person doing the PUG > update knows they need to document something. I think your suggestion works well, Jeff. Have an umbrella ticket for all PUG 3.0 issues derived from RFE, or other enhancements that add parameters or undocumented functionality. I like the idea of linking other BZ issues into the main ticket as the primary tracker. I think Blocks would be the correct status to set for linked bugs: the status of the bug would be reflected with strikethrough once it was completed (or ready to document). If the person documenting the issue has any questions, they ask the questions in the linked development RFE to keep the info together (rather than in the PUG 3.0 umbrella ticket). I'll get the ball rolling on this.
(In reply to comment #7) > Added 3 new parameters that can be set in brands to control the > configuration of web site packages. > > web_dir: The full path to where files will be installed. > > web_cfg: The full path to the Publican site config file. > > web_req: The name of the RPM package that will supply the Publican site > config file. > > > The rationale behind limiting these fields to brands is that this is a > system level task and should not be controlled at the book level. > > Committed revision 1763. need to create custom brand. can be tested locally.
I got a fail upon packaging the brand, specifically at %install. --- Output: Executing(%install): /bin/sh -e /var/tmp/rpm-tmp.cCJppi + umask 022 + cd /home/dmacpher/Books/publican-test/publican-mybrand/tmp/rpm + '[' /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64 '!=' / ']' + rm -rf /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64 ++ dirname /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64 + mkdir -p /home/dmacpher/rpmbuild/BUILDROOT + mkdir /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64 + cd publican-mybrand-0.1 + LANG=C + export LANG + unset DISPLAY + rm -rf /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64 + mkdir -p -m755 /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64/usr/share/publican/Common_Content + publican install_brand --path=/home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64/usr/share/publican/Common_Content + mkdir -p -m755 /home/dmacpher/rpmbuild/BUILDROOT/publican-mybrand-0.1-0.fc17.x86_64/ select=/ /var/tmp/rpm-tmp.cCJppi: line 40: xsl:value-of: No such file or directory error: Bad exit status from /var/tmp/rpm-tmp.cCJppi (%install) --- mybrand's defaults.cfg: # Config::Simple 4.59 # Sat Jun 16 11:28:33 2012 doc_url: "http://www.SETUP.example.com/docs" prod_url: "http://www.SETUP.example.com" web_dir: /home/dmacpher ---- Moving back to ASSIGNED.
^^ Checked publican-3.0-0.fc17.t180.noarch on Fedora 17
Documentation required for new params in comment #7.
Need to retest this one and confirm result; maybe failed for an unrelated reason?
Creating a brand from scratch and setting web_dir in publican.cfg and wwwdir in the brands spec file works for me from HEAD. Not sure I ever pointed out that because the brands spec file isn't regenerated at package time it must be manually updated with the directory change.
Verified in build 3.0.t197