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