I’ve split the documentation into 1.8 and Trunk sections and made sure that all version-specific website information now falls under those two sections. I’ve done this by simply extending our existing tree view. The end result is similar to the Apache Tika website.
I’ve copied across the first 2.0 page, “Dependencies”, though it still needs some work. More to come. -- John > On 5 Jan 2015, at 10:53, John Hewson <j...@jahewson.com> wrote: > > >> On 5 Jan 2015, at 01:15, Maruan Sahyoun <sahy...@fileaffairs.de >> <mailto:sahy...@fileaffairs.de>> wrote: >> >> >> Am 05.01.2015 um 10:01 schrieb John Hewson <j...@jahewson.com >> <mailto:j...@jahewson.com>>: >> >>> >>> >>>> On 4 Jan 2015, at 13:40, Maruan Sahyoun <sahy...@fileaffairs.de >>>> <mailto:sahy...@fileaffairs.de>> wrote: >>>> >>>> Hi >>>> >>>> Am 04.01.2015 um 22:24 schrieb John Hewson <j...@jahewson.com >>>> <mailto:j...@jahewson.com>>: >>>> >>>>> >>>>> >>>>>> On 4 Jan 2015, at 13:18, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>> <mailto:sahy...@fileaffairs.de>> wrote: >>>>>> >>>>>> Hi John, >>>>>> >>>>>> >>>>>> Am 04.01.2015 um 22:05 schrieb John Hewson <j...@jahewson.com >>>>>> <mailto:j...@jahewson.com> <mailto:j...@jahewson.com >>>>>> <mailto:j...@jahewson.com>>>: >>>>>> >>>>>>> >>>>>>>> On 4 Jan 2015, at 11:35, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>> <mailto:sahy...@fileaffairs.de>> wrote: >>>>>>>> >>>>>>>> >>>>>>>>> P.S. I managed to publish a small change as a test, using the >>>>>>>>> web-based CMS. But I’d like to understand (and document?) the >>>>>>>>> complete template and build setup. >>>>>>>>> >>>>>>>> >>>>>>>> Great. >>>>>>>> >>>>>>>> WRT the documentation. There is nothing special on our setup i.e. we >>>>>>>> are using the 'regular' Apache CMS build system. So the documentation >>>>>>>> at http://www.apache.org/dev/cmsref.html >>>>>>>> <http://www.apache.org/dev/cmsref.html> applies. >>>>>>>> >>>>>>>> To give you a quick overview: >>>>>>>> >>>>>>>> Everytime there is a change to the svn source tree a build is >>>>>>>> triggered: >>>>>>>> >>>>>>>> - looking at lib/path.pm to match the entries in content against the >>>>>>>> expressions in path.pm. First match wins. >>>>>>>> - from path.pm selecting the view in lib/view.pm >>>>>>>> - from view.pm selecting the template in templates/ >>>>>>>> - the templates consisting of the html source with django template >>>>>>>> expression for logic >>>>>>>> [https://docs.djangoproject.com/en/1.7/topics/templates/ >>>>>>>> <https://docs.djangoproject.com/en/1.7/topics/templates/>] >>>>>>>> >>>>>>>> Is there something specific you are looking for? >>>>>>> >>>>>>> I’m trying to understand how our JavaDoc gets published, and how the >>>>>>> new docs on git will be published in the future. >>>>>> >>>>>> JavaDoc: that's currently a manual process. I'm creating the directory, >>>>>> and upload a tarball -> >>>>>> http://www.apache.org/dev/cmsref.html#generated-docs >>>>>> <http://www.apache.org/dev/cmsref.html#generated-docs> >>>>>> <http://www.apache.org/dev/cmsref.html#generated-docs >>>>>> <http://www.apache.org/dev/cmsref.html#generated-docs>> >>>>>> git docs: we are not there yet - basically you can reference svn and git >>>>>> repositories from within the Apache CMS. Unfortunately this is not well >>>>>> documented. The documentation for that feature refers to the Apache >>>>>> Thrift project which is using that. See the discussion about the feature >>>>>> implementation. >>>>>> http://grokbase.com/t/thrift/dev/143gp141d0/reconsidering-the-apache-cms >>>>>> <http://grokbase.com/t/thrift/dev/143gp141d0/reconsidering-the-apache-cms> >>>>>> >>>>>> <http://grokbase.com/t/thrift/dev/143gp141d0/reconsidering-the-apache-cms >>>>>> >>>>>> <http://grokbase.com/t/thrift/dev/143gp141d0/reconsidering-the-apache-cms>> >>>>> >>>>> Ok, thanks, I think I have all I need for now. Getting the git >>>>> integration working should be a priority as I’m reluctant to start >>>>> writing docs in git if it may never get up and running. >>>>> >>>> >>>> If you want to do the writeup now I'd suggest that you add the content in >>>> SVN as I can guarantee a certain date until that will be available. As I >>>> wrote the documentation over and above the basics is very poor and one >>>> needs to inspect the sources of other projects. >>> >>> Ok, I’ll add content to SVN. I want to at least rework the existing 1.8 >>> content to apply to 2.0 and add some notes on migration from 1.8 to 2.0. >>> >>>> If you don't mind it would be good to have the following pattern for the >>>> content >>>> >>>> - sections which holds user centric content (e.g. Rendering might be more >>>> meaningful than PDModel) >>>> - if there are multiple entries in a section a README.md and/or index.md >>>> as this will play well with GitHub with an overview of the section and >>>> relative links to the subentries as needed. >>> >>> Sounds good. >>> >>>>> I’m going to try to move the 1.8 information which is scattered around or >>>>> website under a common section, so that we can add a 2.0/trunk section >>>>> soon and begin getting docs ready. >>>> >>>> My plan was to have all documentation under a common section and a version >>>> switch. This way we could reuse that if there is a 2.1 …. - I trust you >>>> have your own ideas. >>> >>> Yes, we will need both sets of docs to be available. I’ve looked at a few >>> different Apache projects and Tika provides what I consider to be the ideal >>> solution http://tika.apache.org/ <http://tika.apache.org/> >>> <http://tika.apache.org/ <http://tika.apache.org/>> with all >>> version-specific docs pages in a per-version subtree in their sidebar. >>> >> >> good example. My thoughts were to >> >> a) have the navigation on top to get some extra space > > We’re not really short on space though, 100 characters for the main body text > width is enough, especially when embedding snippets of code. We’ve got over > 130 right now. > >> b) add the documentation similar to http://cordova.apache.org/docs/en/4.0.0/ >> <http://cordova.apache.org/docs/en/4.0.0/> if you select Documentation in >> the navigation with a documentation related sidebar for the content > > The Cordova website is quite different from PDFBox though, they have a > dedicated documentation website, so a top-level version select makes sense. > Our website is much more like Tika’s (and most other Apache projects) in that > there is mixed version-specific and general purpose content. The downside to > adding a top-level version select to our site is that it makes all content > appear to be version-specific, which it’s not. Tika’s approach really shines > for me - they have very similar content and structure to PDFBox, so their > solution is more relevant to us. > >> c) move all documentation related content into there including Dependencies, >> Building PDFBox and FAQ. > > Yes, definitely, except I’d just make sure that the content is under a > versioned subtree in the sidebar, like Tika. This should take about 5 minutes. > >> d) rename the section 'For Developers' to 'For Contributors’ > > Something like that would clarify things, some Apache projects us > “Development”. > >> e) document some of the contribution for the website in there > > Yes, that would make life easier. > >> f) add at least the JavaDocs for fontbox, xmpbox and preflight > > We should probably add the fontbox JavaDoc to our current pdfbox JavaDoc as > one, as fontbox is a dependency of pdfbox. Preflight should definitely be > separate. I’m not sure about where xmpbox should be. > >> Maybe we do that first and then concentrate on getting the release ready (I >> still have a lot to do on the AcroForms stuff) and get the pdfbox-docs >> integration done afterwards. > > Yes, as SVN is working for now pdfbox-docs can wait. I’ll start adding some > 2.0 docs soon, before I forget what it was I wanted to write... > >> If there are tasks I can help you with just let me know. > > I think I’m on top of things now - thanks for the help. > > — John > >> WDYT? >> >> Maruan >> >> >>>> BR >>>> >>>> Maruan >>>> >>>>> >>>>>> BR >>>>>> Maruan >>>>>> >>>>>> >>>>>>> >>>>>>>> BR >>>>>>>> >>>>>>>> Maruan >>>>>>>> >>>>>>>>> -- John >>>>>>>>> >>>>>>>>>> On 3 Jan 2015, at 16:59, John Hewson <j...@jahewson.com >>>>>>>>>> <mailto:j...@jahewson.com>> wrote: >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> >>>>>>>>>>> On 2 Jan 2015, at 22:47, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>>>>> <mailto:sahy...@fileaffairs.de>> wrote: >>>>>>>>>>> >>>>>>>>>>> Am 03.01.2015 um 04:21 schrieb John Hewson <j...@jahewson.com >>>>>>>>>>> <mailto:j...@jahewson.com>>: >>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>>>> On 2 Jan 2015, at 16:25, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de>> wrote: >>>>>>>>>>>>> >>>>>>>>>>>>>> >>>>>>>>>>>>>> >>>>>>>>>>>>>>> On 1 Jan 2015, at 22:23, Maruan Sahyoun <sahy...@fileaffairs.de >>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de> <mailto:sahy...@fileaffairs.de >>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de>>> wrote: >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> Hi John, >>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> On 1 Jan 2015, at 14:40, Maruan Sahyoun >>>>>>>>>>>>>>>>> <sahy...@fileaffairs.de <mailto:sahy...@fileaffairs.de> >>>>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de >>>>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de>> >>>>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de >>>>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de> >>>>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de >>>>>>>>>>>>>>>>> <mailto:sahy...@fileaffairs.de>>>> wrote: >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> This isn’t a good situation at all, we had a usable >>>>>>>>>>>>>>>>>> documentation system in October and now we have nothing >>>>>>>>>>>>>>>>>> usable, with almost no content and no way to easily >>>>>>>>>>>>>>>>>> contribute. >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> how is the content different from the existing one? There >>>>>>>>>>>>>>>>> wasn't a lot of content and there still isn't. That usable >>>>>>>>>>>>>>>>> documentation system wasn't used a lot. >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> Most of the website is missing, all we have is the cookbook. >>>>>>>>>>>>>>>> There’s no way to build, deploy or preview anything. >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> it's not meant to replace the whole website. That will still >>>>>>>>>>>>>>> reside in the Apache CMS which will pull the docs sources from >>>>>>>>>>>>>>> GitHub (I explained that in a ticket). >>>>>>>>>>>>>> >>>>>>>>>>>>>> Do you mean PDFBOX-2340? I assumed that “pdfbox docs” meant our >>>>>>>>>>>>>> entire website. I guess not. So this means we have some of the >>>>>>>>>>>>>> website on SVN and some of it on Git? And no single revision >>>>>>>>>>>>>> number for the overall site? >>>>>>>>>>>>> >>>>>>>>>>>>> The discussion before pdfbox-docs has been created was to have >>>>>>>>>>>>> the documentation on git not the overall website. The build >>>>>>>>>>>>> system ist still the Apache CMS as is currently in use. That will >>>>>>>>>>>>> have the templates, the build scripts …. - as is today. >>>>>>>>>>>>> >>>>>>>>>>>>>> >>>>>>>>>>>>>>> pdfbox-docs will hold the sources for the documentation. I >>>>>>>>>>>>>>> brought the cookbook entries so one can see some of the >>>>>>>>>>>>>>> structure. >>>>>>>>>>>>>> >>>>>>>>>>>>>> What about the other existing docs? How do I contribute to >>>>>>>>>>>>>> those? On SVN? >>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> We’d agreed that moving to docs to GitHub was an experiment >>>>>>>>>>>>>>>>>> to see if it made contributing easier but it’s had the >>>>>>>>>>>>>>>>>> opposite effect, we’re in a less usable state than ever. It >>>>>>>>>>>>>>>>>> seems like we’d be better off going back to our working SVN >>>>>>>>>>>>>>>>>> documentation and creating a new 2.0 branch from the 1.8 >>>>>>>>>>>>>>>>>> docs and then updating them. We just haven’t realised the >>>>>>>>>>>>>>>>>> benefit from doing things differently. >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> There were no major contributions to the documentation using >>>>>>>>>>>>>>>>> SVN. Everybody could have done it before but didn't. The non >>>>>>>>>>>>>>>>> existing content is not because of GitHub (or SVN). >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> If there’s no advantage to using GitHub then we probably >>>>>>>>>>>>>>>> shouldn’t use it. This was a test to see if there were >>>>>>>>>>>>>>>> benefits… but there seem to be none. >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> So my suggestion is to put the content you are planning to >>>>>>>>>>>>>>>>> contribute into pdfbox-docs. Now if you put it into the CMS >>>>>>>>>>>>>>>>> fine. We can later make it available in pdfbox-docs. >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> I’d like to do that, but unless I need to be able to build and >>>>>>>>>>>>>>>> deploy the docs to the website somehow. >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> I take some of the blame as I didn't find the time to >>>>>>>>>>>>>>>>> enhance/restructure the website - again that's not GitHubs >>>>>>>>>>>>>>>>> fault. >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>> Enhancements are of course welcome, but we need the old >>>>>>>>>>>>>>>> functionality working, at a bare minimum. e.g. where has most >>>>>>>>>>>>>>>> of the website gone? >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> the restructuring is necessary because the pull mechanism needs >>>>>>>>>>>>>>> to be enabled. >>>>>>>>>>>>>>> >>>>>>>>>>>>>>> In addition there needs to be the place for the PDFBox 2 docs >>>>>>>>>>>>>>> together with the old 1.8 docs. That's independent from using >>>>>>>>>>>>>>> SVN or GitHub. >>>>>>>>>>>>>> >>>>>>>>>>>>>> All we need is a branch in SVN. There’s no need to put the 1.8 >>>>>>>>>>>>>> docs on GitHub, they’re going to obsolete in a few months. The >>>>>>>>>>>>>> simplest possible solution is to just create a new 2.0 docs >>>>>>>>>>>>>> branch on SVN. >>>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>>> That's revisiting the git/svn discussion. If there is agreement >>>>>>>>>>>>> that it shall stay on SVN fine. >>>>>>>>>>>>> >>>>>>>>>>>>>>> I have a little more time now so can look into that (and put >>>>>>>>>>>>>>> the AcroForm stuff to the side for the moment). OTOH if you or >>>>>>>>>>>>>>> someone else wants to do it let me know. >>>>>>>>>>>>>> >>>>>>>>>>>>>> I’m a little stuck to be honest, it seems that our documentation >>>>>>>>>>>>>> system is currently non-functional and part of it is on git for >>>>>>>>>>>>>> no clear reason… >>>>>>>>>>>>>> >>>>>>>>>>>>> >>>>>>>>>>>>> We had the git discussion before pdfbox-docs has been created. If >>>>>>>>>>>>> we want to revisit that we can always do. >>>>>>>>>>>>> >>>>>>>>>>>>> Other than that there is a functional documentation system. You >>>>>>>>>>>>> can add to the documentation today using svn only or together >>>>>>>>>>>>> with pdfbox-docs, do a local build for testing and submit your >>>>>>>>>>>>> changes. >>>>>>>>>>>> >>>>>>>>>>>> What is the workflow for updating pdfbox-docs and pushing it to >>>>>>>>>>>> the website? If I make a change to pdfbox-docs what else do I have >>>>>>>>>>>> to do to get that published on the website? >>>>>>>>>>> >>>>>>>>>>> Assuming that the templates, references, scripts are in place you'd >>>>>>>>>>> have to trigger the Apache CMS build which will regenerate the >>>>>>>>>>> website (pulling the pdfbox-docs sources) and publish it to the >>>>>>>>>>> staging website. From there you'd have to publish to the production >>>>>>>>>>> website. The Apache CMS always builds to staging. >>>>>>>>>>> >>>>>>>>>>> You could also use an external build system for the pdfbox-docs >>>>>>>>>>> files and from there push the files to the Apache CMS svn tree or >>>>>>>>>>> upload a compressed archive. Again this will trigger a build to >>>>>>>>>>> staging. Uploading an archive is how we publish the PDFBox javadoc >>>>>>>>>>> files. >>>>>>>>>>> >>>>>>>>>>> If you'd like to update production directly you need to build >>>>>>>>>>> independently from the Apache CMS and push to the production tree. >>>>>>>>>>> There needs to be a configuration file (extpaths.txt) in the >>>>>>>>>>> Apache CMS which will tell the Apache CMS to not overwrite that >>>>>>>>>>> part of the tree. >>>>>>>>>>> >>>>>>>>>>> A more complete description of the possibilities is in >>>>>>>>>>> http://www.apache.org/dev/cmsref.html#external-build >>>>>>>>>>> <http://www.apache.org/dev/cmsref.html#external-build>. >>>>>>>>>> >>>>>>>>>> There seem to be a lot of options and customisations possible with >>>>>>>>>> the Apache CMS. Do we have a step-by-step workflow documented >>>>>>>>>> anywhere specifically describing how the pdfbox website is currently >>>>>>>>>> being managed? >>>>>>>>>> >>>>>>>>>>>> >>>>>>>>>>>>> Now there is no sample doing it this way in the PDFBox CMS >>>>>>>>>>>>> sources as I didn't have the time yet to create one. The Apache >>>>>>>>>>>>> CMS capabilities are documented at >>>>>>>>>>>>> http://www.apache.org/dev/cmsref.html >>>>>>>>>>>>> <http://www.apache.org/dev/cmsref.html> >>>>>>>>>>>>> <http://www.apache.org/dev/cmsref.html >>>>>>>>>>>>> <http://www.apache.org/dev/cmsref.html>>. Some of the more >>>>>>>>>>>>> advanced capabilities are not well documented but need to be >>>>>>>>>>>>> gathered by inspecting the code or looking at other projects >>>>>>>>>>>>> using the Apache CMS. >>>>>>>>>>>>> >>>>>>>>>>>>> BTW no need to wait for me doing these changes as every committer >>>>>>>>>>>>> has access. >>>>>>>>>>>>> >>>>>>>>>>>>> BR >>>>>>>>>>>>> Maruan >>>>>>>>>>>>> >>>>>>>>>>>>>>> BR - Maruan >>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> Maruan >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>> -- John >>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>> On 1 Jan 2015, at 12:52, Maruan Sahyoun >>>>>>>>>>>>>>>>>>> <sahy...@fileaffairs.de <mailto:sahy...@fileaffairs.de>> >>>>>>>>>>>>>>>>>>> wrote: >>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>> the docs shall reside in pdfbox-docs from where they will >>>>>>>>>>>>>>>>>>> be pulled onto the website or looked at directly at github. >>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>> The publishing process to our website is not yet in place >>>>>>>>>>>>>>>>>>> as there is no new content. I'm looking to get the redesign >>>>>>>>>>>>>>>>>>> of the website done to accommodate for the old 1.8 and new >>>>>>>>>>>>>>>>>>> 2.0 release. >>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>> Maruan >>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>> Am 01.01.2015 um 19:38 schrieb John Hewson >>>>>>>>>>>>>>>>>>> <j...@jahewson.com <mailto:j...@jahewson.com>>: >>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>>> Hi All, >>>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>>> We’re getting closer to 2.0 being ready and I’m thinking >>>>>>>>>>>>>>>>>>>> about writing some docs, but currently the situation seems >>>>>>>>>>>>>>>>>>>> to be worse than it was before the docs stated moving to >>>>>>>>>>>>>>>>>>>> GitHub - where are our canonical docs and how can I >>>>>>>>>>>>>>>>>>>> contribute to them? >>>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>>> All I see on GitHub is some old 1.8 stuff and an >>>>>>>>>>>>>>>>>>>> incomplete cookbook for forms. Is this content live >>>>>>>>>>>>>>>>>>>> anywhere? Is there a pay to preview it? >>>>>>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>>>>> -- John >
