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