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