On Mon, Oct 13, 2014 at 01:12:35AM -0600, Pete Travis wrote:

On 10/13/2014 12:34 AM, Jeff Fearn wrote:

...

On 10/10/2014 08:30 PM, Jeffrey Fearn wrote:

...

Hi, Rudi asked me to do a demo of how Fedora could make a rebuilt docs website look, so I've made a demo site & tweaked it a bit. Before I spend too much effort on it I thought I'd open it up for input.

...

I wanted to get a bit more done before the weekend, but time slipped away. I wanted to get it out for some feedback over the weekend so I can do some more on Monday, so I'd thought I'd just put it out there and hope people can understand it is only half baked.

...

Some of the stuff I did for this I liked so I've started migrating the template changes back in to publican, leaving this site with just some colour changes on what a default web_style 2 site will look like. I'll update my fedora people site next week so show what a default site will look like.

...

I've made a script to pull out most of the docs packages from git, and run through a bunch of branches per book, and try to build them with the latest publican. I'll make the script available next week for people who want to build their own copy. It should be useful to QA the process as it spits out a log file out for each repo and branch so you can get a good list of what's broken and what's not. I'll also put those up on my fedora people site next week ... If I have any quota left :D

I've pushed this on to the demo site [1], comments at the top hold the instructions.

It needs tweaks to docsite-publican, hope to get those committed soon.

It also needs Fedora_Splash which contains the blurb on the Fedora products page and the groupings, not sure what to do about that.

It will still work without those things, it just won't look exactly the same.

...

Demo site is https://jfearn.fedorapeople.org/fdocs/en-US/index.html

I think this is a pretty good layout https://jfearn.fedorapeople.org/fdocs/en-US/index.html#Fedora

Colours are hard :-/

Note if you click a group, below the versions, then it filters out all the other groups.

Note that in the "System administration" group for Fedora 20 there is an external link "The Ways And Means Of Pants" which is a fake URL, if you have a couple of examples of real external links you'd like in that group, or any other group, I'd be happy to swap out the fake one.

I haven't changed the brand XSL for the html payload, I'd like to remove the old left and right logos at the top of the pages. They aren't really needed given the menu content.

e.g. https://jfearn.fedorapeople.org/fdocs/en-US/Fedora/20/html/Installation_Guid...

bah I just noticed a bug on that page, the first two items in the navigation menu are swapped ... :(

I'm sure there are lots more :}

I've built html, html-single, epub & pdf.

The site is only in en-US, it's 417M and I'm not sure the hosting people would be happy if I hosted more languages :)

Anyway, it's Friday evening and the wine is calling, please reply if you have any ideas or feedback, beware that I'm currently hacking on the publican devel branch, so I might steal any really cool ideas for publican.next ;)

Cheers, Jeff.

P.S. All the RSS feeds on there should work, but you probably do not

want to sign up for that site!

Cheers, Jeff.

1: https://jfearn.fedorapeople.org/fdocs/rebuild_site.sh

Hey Jeff,

I'm exited to see your interest in our Publican site. We've been trying to build a system with publican-created src.rpms built by koji, and installed to a virtual machine. The infrastructure part has gone fairly well; any package we push out is automatically installed and the site updated.

The part of the process I've really struggled with is the interaction between the branding, the table of contents stuff, the landing page, the splash (which I wasn't aware of as a discrete document type,) the CSS applied to the toc/landing page/splash, the spec file templates used for landing pages or docs or sites or splashes, the publican.cfg for the landing page or the site settings... well, I'll just say every time I try to work on it, I get lost. I realize that's a very non-specific problem description, but after hours of working with the existing site, with CSS that people on our team worked out, or just starting a publican site from scratch following your user guide, I don't feel like I'm at the point of even intelligently asking for help.

rkratky and yruseva worked up CSS for a web_style=2 site that I rather like, at https://rkratky.fedorapeople.org/docsweb/mockup/en-US/index.html . I really like elements from your demo too, like the secondary categories and the format selection icons (although replicating the Adobe logo for PDFs probably should go :P ). The social media things at the bottom are intriguing; our marketing team would probably like to explore the potential there.

Ideally, I'd like to have all of the components and docs we need tagged into the el6-docs repo, and the site would rebuild by simply installing all the Publican document packages available on a clean virtual machine. Can you help us put all these pieces together into a replicatable site, or at least talk me through some stumbling blocks sometime?

Optimally, the Fedora Docs site should have the same look and feel that the Design team is doing for other Fedora websites. Ryan Lerch has been working on an implementation of bootstrap that would unify all our Fedora sites/subdomains. It would be great to see the Docs site both use that theme, and also have the docs-specific features rkratky, jfearn, et al. are interested to provide.

cc'ing rlerch and mattdm for awareness since I'm not sure either of them is on the Docs list.

Hi Paul,

----- Original Message -----

On Mon, Oct 13, 2014 at 01:12:35AM -0600, Pete Travis wrote:

...

On 10/13/2014 12:34 AM, Jeff Fearn wrote:

...

On 10/10/2014 08:30 PM, Jeffrey Fearn wrote:

...

Hi, Rudi asked me to do a demo of how Fedora could make a rebuilt docs website look, so I've made a demo site & tweaked it a bit. Before I spend too much effort on it I thought I'd open it up for input.

...

I wanted to get a bit more done before the weekend, but time slipped away. I wanted to get it out for some feedback over the weekend so I can do some more on Monday, so I'd thought I'd just put it out there and hope people can understand it is only half baked.

...

Some of the stuff I did for this I liked so I've started migrating the template changes back in to publican, leaving this site with just some colour changes on what a default web_style 2 site will look like. I'll update my fedora people site next week so show what a default site will look like.

...

I've made a script to pull out most of the docs packages from git, and run through a bunch of branches per book, and try to build them with the latest publican. I'll make the script available next week for people who want to build their own copy. It should be useful to QA the process as it spits out a log file out for each repo and branch so you can get a good list of what's broken and what's not. I'll also put those up on my fedora people site next week ... If I have any quota left :D

I've pushed this on to the demo site [1], comments at the top hold the instructions.

It needs tweaks to docsite-publican, hope to get those committed soon.

It also needs Fedora_Splash which contains the blurb on the Fedora products page and the groupings, not sure what to do about that.

It will still work without those things, it just won't look exactly the same.

...

Demo site is https://jfearn.fedorapeople.org/fdocs/en-US/index.html

I think this is a pretty good layout https://jfearn.fedorapeople.org/fdocs/en-US/index.html#Fedora

Colours are hard :-/

Note if you click a group, below the versions, then it filters out all the other groups.

Note that in the "System administration" group for Fedora 20 there is an external link "The Ways And Means Of Pants" which is a fake URL, if you have a couple of examples of real external links you'd like in that group, or any other group, I'd be happy to swap out the fake one.

I haven't changed the brand XSL for the html payload, I'd like to remove the old left and right logos at the top of the pages. They aren't really needed given the menu content.

e.g. https://jfearn.fedorapeople.org/fdocs/en-US/Fedora/20/html/Installation_Guid...

bah I just noticed a bug on that page, the first two items in the navigation menu are swapped ... :(

I'm sure there are lots more :}

I've built html, html-single, epub & pdf.

The site is only in en-US, it's 417M and I'm not sure the hosting people would be happy if I hosted more languages :)

Anyway, it's Friday evening and the wine is calling, please reply if you have any ideas or feedback, beware that I'm currently hacking on the publican devel branch, so I might steal any really cool ideas for publican.next ;)

Cheers, Jeff.

P.S. All the RSS feeds on there should work, but you probably do not

want to sign up for that site!

Cheers, Jeff.

1: https://jfearn.fedorapeople.org/fdocs/rebuild_site.sh

Hey Jeff,

I'm exited to see your interest in our Publican site. We've been trying to build a system with publican-created src.rpms built by koji, and installed to a virtual machine. The infrastructure part has gone fairly well; any package we push out is automatically installed and the site updated.

The part of the process I've really struggled with is the interaction between the branding, the table of contents stuff, the landing page, the splash (which I wasn't aware of as a discrete document type,) the CSS applied to the toc/landing page/splash, the spec file templates used for landing pages or docs or sites or splashes, the publican.cfg for the landing page or the site settings... well, I'll just say every time I try to work on it, I get lost. I realize that's a very non-specific problem description, but after hours of working with the existing site, with CSS that people on our team worked out, or just starting a publican site from scratch following your user guide, I don't feel like I'm at the point of even intelligently asking for help.

rkratky and yruseva worked up CSS for a web_style=2 site that I rather like, at https://rkratky.fedorapeople.org/docsweb/mockup/en-US/index.html . I really like elements from your demo too, like the secondary categories and the format selection icons (although replicating the Adobe logo for PDFs probably should go :P ). The social media things at the bottom are intriguing; our marketing team would probably like to explore the potential there.

Ideally, I'd like to have all of the components and docs we need tagged into the el6-docs repo, and the site would rebuild by simply installing all the Publican document packages available on a clean virtual machine. Can you help us put all these pieces together into a replicatable site, or at least talk me through some stumbling blocks sometime?

Optimally, the Fedora Docs site should have the same look and feel that the Design team is doing for other Fedora websites.

Ryan Lerch has been working on an implementation of bootstrap that would unify all our Fedora sites/subdomains. It would be great to see the Docs site both use that theme, and also have the docs-specific features rkratky, jfearn, et al. are interested to provide.

Ryan is responsible for a reasonable amount of the styling and structure of publican websites and is familiar with the template system it's uses, so it should be doable.

How much work it is depends on how different the style is and how intrusive it needs to be to get it done. e.g. getting publican integrated with the Red Hat portal was a huge investment.

Of course if Ryan wants to avoid all that nasty integration work and wanted to redo the common theme from scratch using bootstrap, so that FDocs only needs some minor tweaking, I'd "begrudgingly" accept that :D

cc'ing rlerch and mattdm for awareness since I'm not sure either of them is on the Docs list.

Cheers, Jeff.

On 10/23/2014 04:21 PM, Jeff Fearn wrote:

<TRIM!>

So this thread has kind of died, I think it's because using bootstrap with the current HTML output is a monstrous job.

I'd like to progress with getting the site updated to something similar to my demo then start a separate, longer, process to change the HTML publican generates so that it's much easier for people to radically change the styling.

Thoughts?

Cheers, Jeff.

Hey Jeff,

Thanks again for spending some time on IRC recently. I've spent a bit more time on this, and have developed a few questions I hope you can answer.

First, one of the things I've been struggling with was getting the style applied to the homepage. After trying a number of misguided things, I actually looked at $sitehome/en-US/index.html and found this:

$('#splash').load("https://admin.fedoraproject.org/docs-backend//en-US/splash.html .article");

The main copy on the page is loaded by this function, and of course it strips the <head> out - so no CSS comes with. What we *do* get is:

- chrome.css - site_overrides.css - splash.css

With your help, site_overrides.css is coming from the docsite-publican (home) package now. The other two files I had to manually copy in from /usr/share/publican, and if I recall correctly, I ended up copying over all of /usr/share/publican/sitetemplate/ . - Is there an RPM method for doing this?

The CSS files that aren't coming along are:

- db4.css - brand.css - print.css

This doesn't seem right. The home page should have the branding, right? Is a custom site template needed here?

On 01/11/2015 05:13 PM, Jeff Fearn wrote:

Hi Pete,

On 12/20/2014 03:10 PM, Pete Travis wrote:

...

On 10/23/2014 04:21 PM, Jeff Fearn wrote:

<TRIM!>

...

So this thread has kind of died, I think it's because using bootstrap with the current HTML output is a monstrous job.

I'd like to progress with getting the site updated to something similar to my demo then start a separate, longer, process to change the HTML publican generates so that it's much easier for people to radically change the styling.

Thoughts?

Cheers, Jeff.

Hey Jeff,

Thanks again for spending some time on IRC recently. I've spent a bit more time on this, and have developed a few questions I hope you can answer.

First, one of the things I've been struggling with was getting the style applied to the homepage. After trying a number of misguided things, I actually looked at $sitehome/en-US/index.html and found this:

$('#splash').load("https://admin.fedoraproject.org/docs-backend//en-US/splash.html .article");

The main copy on the page is loaded by this function, and of course it strips the <head> out - so no CSS comes with.

FYI we did this because loading the second header in to the page had some very weird effects on some browsers.

That's logical, two <head>s doesn't make sense. The result, though, is that the styles that would apply to the main content section aren't ever loaded, and we loose some consistency between the home page and the books. Is that something to just accept, or can you offer some suggestion or enhancement?

...

What we *do* get is:

• chrome.css
• site_overrides.css
• splash.css

With your help, site_overrides.css is coming from the docsite-publican (home) package now. The other two files I had to manually copy in from /usr/share/publican, and if I recall correctly, I ended up copying over all of /usr/share/publican/sitetemplate/ . - Is there an RPM method for doing this?

sitetemplate gets copied over whenever you run "publican update_site".

I see. Would it make sense to call `publican update_site` in %post of brand or splash packages? I can't see that it would hurt anything, and would get closer to a package-only deployment.

...

The CSS files that aren't coming along are:

• db4.css
• brand.css
• print.css

This doesn't seem right. The home page should have the branding, right? Is a custom site template needed here?

No, db4.css & print.css also get put in place by running update_site.

brand.css was removed and should not be being required.

Are you using publican from the devel git branch? I did do some changes to get the shiny happening, but I'm fresh back from holidays and can't recall everything I did specifically for this :}

Cheers, Jeff.

hmm.. I'll have to investigate our usage of brand.css. Without it, brand-specific style would only come from site_overrides.css and not the brand; with the latter not being provided by the brand, it seems like taking it out means maintaining the same styles in both files.

Publican installed here is publican-4.1.3-0.el6.noarch. I suppose I, or someone anyway, should take responsibility for updating the el6-docs tag's publican and dependencies... but, I'm not a fan of putting our production site on publican git.

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

Hi all, just to update on this topic.

My demo site [1] is pretty stable now. It's completely built from Fedora Docs git repos and the publican devel branch with my updated build script [2].

The top of the script contains full instructions for creating a test site, it's almost all automated or cut-n-paste to the command line, so anyone should be able to get a test site up.

Warning: It does take a long time to build the first time as it has to check out al the books :)

Lee is currently doing some fixes for Red Hat docs, so we intend to release a new version of Publican in 2-3 weeks. That release will contain all the changes in the devel branch.

Cheers, Jeff.

1: https://jfearn.fedorapeople.org/fdocs/en-US/index.html 2: https://jfearn.fedorapeople.org/rebuild_site.sh

Should we have styling more like the getfedora.org site? Fedora Magazine? The Spins page? I think we can easily take some of their visual elements.

The layout is quite nice though. Once we are ready to generate docs in whatever tool-chain we want, it will be awesome.

Did you give any thought as to how to help users understand why we have three categories of documentation for each release? Should we now group by the fedora.next groupings?

regards,

bex

On Feb 24, 2015, at 6:57 AM, Jeff Fearn jfearn@redhat.com wrote:

Signed PGP part On 02/21/2015 10:30 AM, Jeff Fearn wrote:

...

Hi all, just to update on this topic.

My demo site [1] is pretty stable now. It's completely built from Fedora Docs git repos and the publican devel branch with my updated build script [2].

The top of the script contains full instructions for creating a test site, it's almost all automated or cut-n-paste to the command line, so anyone should be able to get a test site up.

Warning: It does take a long time to build the first time as it has to check out al the books :)

Lee is currently doing some fixes for Red Hat docs, so we intend to release a new version of Publican in 2-3 weeks. That release will contain all the changes in the devel branch.

Cheers, Jeff.

1: https://jfearn.fedorapeople.org/fdocs/en-US/index.html 2: https://jfearn.fedorapeople.org/rebuild_site.sh

Shout out to Luke Brooker who gave me some CSS patches for the breadcrumb menus on the test site.

They where frustrating me no end, so thanks mate!

https://jfearn.fedorapeople.org/fdocs/en-US/index.html#Fedora

Cheers, Jeff.

-- docs mailing list docs@lists.fedoraproject.org To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs

On Feb 25, 2015, at 2:54 AM, Jeff Fearn jfearn@redhat.com wrote:

Signed PGP part On 02/24/2015 04:49 PM, Brian (bex) Exelbierd wrote:

...

Should we have styling more like the getfedora.org site? Fedora Magazine? The Spins page? I think we can easily take some of their visual elements.

Possibly, I'm only making the base for that kind of work to follow on.

cool.

...

The layout is quite nice though. Once we are ready to generate docs in whatever tool-chain we want, it will be awesome.

This is orthogonal to such changes.

I realize that. What wasn’t clear to me from your email is whether we could hook this up today or not. It also wasn’t clear whether this was prepared to be tooled or was a tool.

...

Did you give any thought as to how to help users understand why we have three categories of documentation for each release?

You mean the groups? e.g. "Getting started", "System administration", etc?

Actually I meant Fedora vs Fedora Contributor vs Fedora Draft Documentation.

I don’t know if those are clear. Since you were re-imaginging the site, I was curious what your thoughts were.

...

Should we now group by the fedora.next groupings?

This is orthogonal to this demo as you can easily change groups once the updated tool chain is being used.

It could be orthogonal or not depending on how we do the grouping and how the groups I mentioned above are generated.

FWIW If you take a look at the Red Hat docs you will not see this kind of division even though RH have been doing variants for a long time.

I am familiar with the RH platform doc set. I also know where some of the rough edges with the variants are. However, the RH customer, it seems to be believed, is different from the Fedora customer. So what is good for the goose may not be good for the gander.

I think it'd be a lot of work and/or duplication to split up the docs to cover variants.

I think there are options around a content strategy that could be very interesting if we go down a split doc set road.

regards,

bex

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1

On 02/26/2015 09:00 AM, Jeff Fearn wrote:

This is baked and ready to go, just waiting on some changes for unrelated RH docs requirements to release a new Publican.

And to be very clear, the script I linked to could be used to regenerate the current docs git published site by adding one parameter to the command line.

$ rebuild_site.sh -p $path_to_publican_git -w $path_to_docs_site_git

Some of the old books might need some XML cleaned up if you want to build all the old versions :)

Once we push publican 4.3.0 the script will need a tweak so you don't need to set -p ... I'll try and get that done today if I have time.

I've update the script so that if you don't specify -p it will use the installed publican package.

FYI I have fixed a bug where the external links didn't show up in the book list menu.

That should be all baked now and we are just scheduling some testing for RH docs to make sure we don't break things post upgrade.

Cheers, Jeff.

Hi Pete,

----- Original Message -----

On 10/13/2014 12:34 AM, Jeff Fearn wrote:

...

On 10/10/2014 08:30 PM, Jeffrey Fearn wrote:

...

Hi, Rudi asked me to do a demo of how Fedora could make a rebuilt

docs website look, so I've made a demo site & tweaked it a bit. Before I spend too much effort on it I thought I'd open it up for input.

...

I wanted to get a bit more done before the weekend, but time slipped

away. I wanted to get it out for some feedback over the weekend so I can do some more on Monday, so I'd thought I'd just put it out there and hope

...

people can understand it is only half baked.

...

Some of the stuff I did for this I liked so I've started migrating

the template changes back in to publican, leaving this site with just some colour changes on what a default web_style 2 site will look like. I'll

...

update my fedora people site next week so show what a default site

will look like.

...

I've made a script to pull out most of the docs packages from git,

and run through a bunch of branches per book, and try to build them with the latest publican. I'll make the script available next week for people who

...

want to build their own copy. It should be useful to QA the process

as it spits out a log file out for each repo and branch so you can get a good list of what's broken and what's not. I'll also put those up on my

...

fedora people site next week ... If I have any quota left :D

I've pushed this on to the demo site [1], comments at the top hold the instructions.

It needs tweaks to docsite-publican, hope to get those committed soon.

It also needs Fedora_Splash which contains the blurb on the Fedora products page and the groupings, not sure what to do about that.

It will still work without those things, it just won't look exactly the same.

...

Demo site is https://jfearn.fedorapeople.org/fdocs/en-US/index.html

...

I think this is a pretty good layout

https://jfearn.fedorapeople.org/fdocs/en-US/index.html#Fedora

...

Colours are hard :-/

...

Note if you click a group, below the versions, then it filters out

all the other groups.

...

Note that in the "System administration" group for Fedora 20 there

is an external link "The Ways And Means Of Pants" which is a fake URL, if you have a couple of examples of real external links you'd like in that

...

group, or any other group, I'd be happy to swap out the fake one.

...

I haven't changed the brand XSL for the html payload, I'd like to

remove the old left and right logos at the top of the pages. They aren't really needed given the menu content.

...

e.g.

https://jfearn.fedorapeople.org/fdocs/en-US/Fedora/20/html/Installation_Guid...

...

bah I just noticed a bug on that page, the first two items in the

navigation menu are swapped ... :(

...

I'm sure there are lots more :}

...

I've built html, html-single, epub & pdf.

...

The site is only in en-US, it's 417M and I'm not sure the hosting

people would be happy if I hosted more languages :)

...

Anyway, it's Friday evening and the wine is calling, please reply if

you have any ideas or feedback, beware that I'm currently hacking on the publican devel branch, so I might steal any really cool ideas for

...

publican.next ;)

...

Cheers, Jeff.

...

P.S. All the RSS feeds on there should work, but you probably do not

want to sign up for that site!

Cheers, Jeff.

1: https://jfearn.fedorapeople.org/fdocs/rebuild_site.sh

Hey Jeff,

I'm exited to see your interest in our Publican site. We've been trying to build a system with publican-created src.rpms built by koji, and installed to a virtual machine. The infrastructure part has gone fairly well; any package we push out is automatically installed and the site updated.

The part of the process I've really struggled with is the interaction between the branding, the table of contents stuff, the landing page, the splash (which I wasn't aware of as a discrete document type,) the CSS applied to the toc/landing page/splash, the spec file templates used for landing pages or docs or sites or splashes, the publican.cfg for the landing page or the site settings... well, I'll just say every time I try to work on it, I get lost. I realize that's a very non-specific problem description, but after hours of working with the existing site, with CSS that people on our team worked out, or just starting a publican site from scratch following your user guide, I don't feel like I'm at the point of even intelligently asking for help.

Yeah you'd think a tool like publican which is used almost exclusively by writers would have better docs, but getting writers to help document the stuff has always been extremely painful and unsuccessful. :(

The section in the PUG is [1] if there are specific things that are missing or confusing bugs are appreciated.

There have been some bugs too, like fairly recently (in publican terms) I removed the brand CSS from the splash pages and did a lot of separation of the CSS content because it was just a nightmare to maintain.

I'll try and describe how it works on my demo site as it up to date and should have the least complex interactions.

The site is basically split in to two areas, the splash pages and the books.

Both areas use chrome.css to style the menu.

The splash area uses splash.css to style body content.

The book area uses db4.css or db5.css to style body content. I split them because having one CSS file for docbook4 and docbook5 was unmaintainable.

The book area uses brand.css to override the style of body content. You need one brand for db4 and one for db5, so you don't need to try and style both in the one brand.css file.

Both areas use site-overides.css to override the styles.

Note that the CSS still has some overlap but I am gradually moving the styles in to the right CSS files.

There are 3 levels of splash pages, site (or welcome page), product and version. These are normal publican books that are processed slightly differently.

The site level splash page contains: 1: site-overides.css 2: the front page blurb 3: Ads for the splash pages (if you want them)

The product level splash page contains: 1: the product page blurb 2: Groups for books 3: External links

The version level splash page contains: 1: the product version page blurb

Templates are another story, you should not have to modify the spec file template, if you have specific requirements we can either get it added as a brand config option or I can show you how to override the templates entirely in your brand.

The splash pages are also generated using templates, and again with specific requirements we can look to parameterise them or override them entirely.

rkratky and yruseva worked up CSS for a web_style=2 site that I rather like, at https://rkratky.fedorapeople.org/docsweb/mockup/en-US/index.html .

Yeah my stuff is web_style 2 as well since AFAIK no one is using web_style 1 and it's not QA'd ATM.

lol I wish I'd know about this before, it's very similar really :P

I really like elements from your demo too, like the secondary categories and the format selection icons (although replicating the Adobe logo for PDFs probably should go :P )

Those glyphs are from font awesome, it's GPL compatible and should be fine.

. The social media things at the bottom are intriguing; our marketing team would probably like to explore the potential there.

Yeah I never understood why no one ever uses footer in teh site.cfg file ... although any text on the links would not be translatable :(

Ideally, I'd like to have all of the components and docs we need tagged into the el6-docs repo, and the site would rebuild by simply installing all the Publican document packages available on a clean virtual machine. Can you help us put all these pieces together into a replicatable site, or at least talk me through some stumbling blocks sometime?

Yeah I'm happy to help get this up and running for you all, publishing should be an easy last step not a high jump.

Cheers, Jeff.

On 10/13/2014 03:22 PM, Jeffrey Fearn wrote:

Hi Pete,

TRIM!

Hey Jeff,

I'm exited to see your interest in our Publican site. We've been trying to build a system with publican-created src.rpms built by koji, and installed to a virtual machine. The infrastructure part has gone fairly well; any package we push out is automatically installed and the site updated.

The part of the process I've really struggled with is the interaction between the branding, the table of contents stuff, the landing page, the splash (which I wasn't aware of as a discrete document type,) the CSS applied to the toc/landing page/splash, the spec file templates used for landing pages or docs or sites or splashes, the publican.cfg for the landing page or the site settings... well, I'll just say every time I try to work on it, I get lost. I realize that's a very non-specific problem description, but after hours of working with the existing site, with CSS that people on our team worked out, or just starting a publican site from scratch following your user guide, I don't feel like I'm at the point of even intelligently asking for help. Yeah you'd think a tool like publican which is used almost exclusively by writers would have better docs, but getting writers to help document the stuff has always been extremely painful and unsuccessful. :(

The section in the PUG is [1] if there are specific things that are missing or confusing bugs are appreciated.

There have been some bugs too, like fairly recently (in publican terms) I removed the brand CSS from the splash pages and did a lot of separation of the CSS content because it was just a nightmare to maintain.

I'll try and describe how it works on my demo site as it up to date and should have the least complex interactions.

The site is basically split in to two areas, the splash pages and the books.

Both areas use chrome.css to style the menu.

The splash area uses splash.css to style body content.

The book area uses db4.css or db5.css to style body content. I split them because having one CSS file for docbook4 and docbook5 was unmaintainable.

The book area uses brand.css to override the style of body content. You need one brand for db4 and one for db5, so you don't need to try and style both in the one brand.css file.

Both areas use site-overides.css to override the styles.

Note that the CSS still has some overlap but I am gradually moving the styles in to the right CSS files.

There are 3 levels of splash pages, site (or welcome page), product and version. These are normal publican books that are processed slightly differently.

The site level splash page contains: 1: site-overides.css 2: the front page blurb 3: Ads for the splash pages (if you want them)

The product level splash page contains: 1: the product page blurb 2: Groups for books 3: External links

The version level splash page contains: 1: the product version page blurb

Templates are another story, you should not have to modify the spec file template, if you have specific requirements we can either get it added as a brand config option or I can show you how to override the templates entirely in your brand.

The splash pages are also generated using templates, and again with specific requirements we can look to parameterise them or override them entirely.

...

rkratky and yruseva worked up CSS for a web_style=2 site that I rather like, at https://rkratky.fedorapeople.org/docsweb/mockup/en-US/index.html .

Yeah my stuff is web_style 2 as well since AFAIK no one is using web_style 1 and it's not QA'd ATM.

lol I wish I'd know about this before, it's very similar really :P

...

I really like elements from your demo too, like the secondary categories and the format selection icons (although replicating the Adobe logo for PDFs probably should go :P )

Those glyphs are from font awesome, it's GPL compatible and should be fine.

...

. The social media things at the bottom are intriguing; our marketing team would probably like to explore the potential there.

Yeah I never understood why no one ever uses footer in teh site.cfg file ... although any text on the links would not be translatable :(

...

Ideally, I'd like to have all of the components and docs we need tagged into the el6-docs repo, and the site would rebuild by simply installing all the Publican document packages available on a clean virtual machine. Can you help us put all these pieces together into a replicatable site, or at least talk me through some stumbling blocks sometime?

Yeah I'm happy to help get this up and running for you all, publishing should be an easy last step not a high jump.

Cheers, Jeff.

Hi again,

Thanks for bring this thread up again. Sorry for such an open-ended question, but can you list out the RPMs we should have, and what RPMs the mentioned files should belong to? The changes to the CSS layout you're describing sound friendly, but I was confused to begin with :P

Like, the splash - is that docsite-publican for us? The site-overrides.css - that doesn't go in the publican-fedora brand with all the other css? Where do the product splash pages come from? How do I build a product version level splash? What should be providing chrome.css? Since some of these files aren't in existing RPMs, I'm not sure where to put them, and it seems like the SPECs are hardcoded by publican.

I contrived a site[1] where the splash? pages seemed to install to something like /var/www/html/ - but all the docs installed to something like /var/www/html/docs/, and the latter directory had resources that the html in the former wanted. I'm sure I went wrong somewhere along the way, or just have a tragic misconception about the way it works. Trying to wrap my mind around what packages installed what files and where is how I wandered off into poking at spec file templates; I don't *know* that I want spec template changes, I just know I haven't been able to produce RPMs that provide the expected result. I moved some things in manually, but it still doesn't quite turn out as I expect.

With file ownership out of the way, is there an ordering concern? ie change the brand, package the brand, change the site splash, build the site splash with the new brand, then install those packages before adding docs, then install the product splashes?

Thanks again for your patience, and persistence.

[1] docs-backend-01.phx2.fedoraproject.org viewable via https://admin.fedoraproject.org/docs-backend/ @sysadmin-docs (notably rudi) have ssh access if you want more info directly from the box