> On 4 Jan 2015, at 13:40, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: > > Hi > > Am 04.01.2015 um 22:24 schrieb John Hewson <j...@jahewson.com>: > >> >> >>> On 4 Jan 2015, at 13:18, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >>> >>> Hi John, >>> >>> >>> Am 04.01.2015 um 22:05 schrieb John Hewson <j...@jahewson.com >>> <mailto:j...@jahewson.com>>: >>> >>>> >>>>> On 4 Jan 2015, at 11:35, Maruan Sahyoun <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 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/] >>>>> >>>>> 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> >>> 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> >> >> 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/> with all version-specific docs pages in a per-version subtree in their sidebar. > BR > > Maruan > >> >>> BR >>> Maruan >>> >>> >>>> >>>>> BR >>>>> >>>>> Maruan >>>>> >>>>>> -- John >>>>>> >>>>>>> On 3 Jan 2015, at 16:59, John Hewson <j...@jahewson.com> wrote: >>>>>>> >>>>>>> >>>>>>> >>>>>>>> On 2 Jan 2015, at 22:47, Maruan Sahyoun <sahy...@fileaffairs.de> wrote: >>>>>>>> >>>>>>>> Am 03.01.2015 um 04:21 schrieb John Hewson <j...@jahewson.com>: >>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>>> On 2 Jan 2015, at 16:25, Maruan Sahyoun <sahy...@fileaffairs.de> >>>>>>>>>> wrote: >>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>>> On 1 Jan 2015, at 22:23, Maruan Sahyoun <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>>> 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. >>>>>>> >>>>>>> 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>. 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> 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>: >>>>>>>>>>>>>>>> >>>>>>>>>>>>>>>>> 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 >> >
