> 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? 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 >
